MIZ OKI Reference Architecture

Version: 6.9.1 Last Updated: January 10, 2026 Status: Production-Ready Industry Alignment: ~85% of emerging AI marketing orchestration best practices

Executive Summary

MIZ OKI is a production-grade autonomous marketing intelligence platform that implements the SRPVDAL (Sense-Reason-Decide-Act-Learn) pipeline with full safety guarantees. This document serves as the definitive reference architecture for building similar systems.

Key Differentiators

1. Architecture Principles

1.1 Safe Autonomy

Every autonomous action must be: - Explainable: Full decision trace from input to output - Reversible: Pre-state capture and platform-specific rollback APIs - Bounded: ReLU gates, guardrails, and circuit breakers prevent runaway actions - Auditable: Complete commit log for compliance and debugging

1.2 ReLU Gate Philosophy

ΔROI = E[revenue_with_action] - E[revenue_without] - incremental_cost

if ΔROI ≤ 0:
    return 0  # BLOCK (like neural network ReLU)
elif safety_checks_pass:
    return ΔROI  # ALLOW
else:
    return 0  # BLOCK

Only positive-ROI actions propagate forward. This ensures the system cannot take value-destroying actions.

1.3 Capability-Driven Design

Tools self-describe their capabilities via JSON-LD manifests with: - Input/output JSON schemas - Cost hints and rate limits - Risk levels and required approvals - OAuth scopes per RFC 8707

2. SRPVDAL Pipeline

2.1 SENSE Stage

Purpose: Ingest signals from all sources, normalize to typed nodes/edges, resolve identities.

Key Components: - Event ingestion from web, app, offline, CRM - Identity resolution via SHA256(email) → CrossPlatformID - Click ID stitching (GCLID, WBRAID, GBRAID, FBP, FBC) - Consent mode integration (GDPR, CCPA)

Firestore Collections: - kg_events: Raw event stream - kg_users: Cross-platform identity graph - kg_clicks: Click ID mappings

Code Location: srpvdal_autonomous_integration.py:833-882

2.2 REASON Stage

Purpose: Form hypotheses about what's happening using retrieval + reasoning over KG.

Key Components: - Knowledge Graph Brain (neuro-symbolic fusion) - CATE (Conditional Average Treatment Effect) estimation - MOA/MOE ensemble (4 Virtuoso models) - Graph traversal with configurable strategies (BFS, DFS, A*, best-first)

Fusion Strategies: - Weighted average: α × symbolic + (1-α) × neural - Max confidence: argmax(symbolic_conf, neural_conf) - Bayesian: P(H|E1,E2) ∝ P(E1|H) × P(E2|H) × P(H) - Dempster-Shafer: Belief mass combination

Code Location: knowledge_graph_brain_integration.py

2.3 DECIDE Stage

Purpose: Propose actions with expected utility and validate against constraints.

Key Components: - ΔROI calculation per action - ReLU gate evaluation - 6-layer guardrail enforcement: 1. Consent (opted-in check) 2. Budget ($50K/day global, per-user caps) 3. Rate limits (API quotas, user touchpoints) 4. Quality (model confidence, freshness) 5. Circuit breakers (ROAS < 0.8x triggers stop) 6. Geo routing (EU data residency)

Action Types:

BID_UP, BID_DOWN, BUDGET_INCREASE, BUDGET_DECREASE,
PAUSE, ENABLE, CREATIVE_ROTATE, AUDIENCE_EXPAND,
AUDIENCE_SUPPRESS, SEND_EMAIL, SEND_SMS

Code Location: srpvdal_autonomous_integration.py:884-951

2.4 ACT Stage

Purpose: Execute actions on platforms with idempotency and state capture.

Key Components: - Idempotency key generation: SHA256(action:entity:hour) - Pre-state capture to Firestore before any mutation - Platform API calls (Google Ads v18, Meta v21, GA4 MP) - Post-state capture for verification

Supported Platforms: | Platform | API Version | Capabilities | |:---------|:------------|:-------------| | Google Ads | v18 | Bids, budgets, status, PMax creation | | Meta Ads | v21.0 | Campaigns, CAPI, Custom Audiences | | GA4 | v2 | Measurement Protocol, EU endpoints | | SendGrid/Klaviyo | Latest | Email/SMS triggers |

Code Location: srpvdal_autonomous_integration.py:953-1021

2.5 LEARN Stage

Purpose: Reconcile outcomes back into KG, update models, enable rollback.

Key Components: - Outcome observation (actual vs predicted) - CATE model updates with new data - Audit logging to srpvdal_audit_log - Rollback triggering on poor performance

Rollback Conditions: - ROAS drops below 0.8× target for 3+ hours - CPA exceeds 2× target - Conversion tracking loss detected - Manual emergency stop

Code Location: platform_rollback_integration.py

3. Guard Architecture

3.1 Guard Types

3.2 Circuit Breaker States

CLOSED → OPEN → HALF_OPEN → CLOSED
         ↑         ↓
         └─────────┘

CLOSED: Normal operation
OPEN: Tripped, blocking all actions (triggered by performance issues)
HALF_OPEN: Testing recovery (limited traffic)

3.3 Guardrails Configuration

guardrails:
  relu_gates:
    primary:
      require_positive_delta_roi: true
      min_delta_roi: 0.0
  budget:
    global:
      max_daily_spend_usd: 50000
    audience:
      max_spend_per_user_usd: 50
  rate_limits:
    user_touchpoints:
      max_daily_impressions: 10
  circuit_breakers:
    performance:
      trigger_if_roas_below: 0.8
      trigger_if_cpa_above_pct: 200

4. MCP Capability Registry

4.1 Capability Descriptor (JSON-LD)

{
  "@context": "https://schema.org/",
  "@type": "SoftwareApplication",
  "id": "google_ads.campaigns.mutate:v1",
  "name": "Google Ads → Mutate Campaigns",
  "description": "Create, update, or remove campaigns",
  "endpoint": {
    "url": "https://googleads.googleapis.com/v18/customers/{id}/campaigns:mutate",
    "method": "POST",
    "auth_type": "oauth2",
    "timeout_seconds": 30
  },
  "input_schema": {...},
  "output_schema": {...},
  "rate_limit": {"unit": "minute", "limit": 60},
  "required_scopes": ["https://www.googleapis.com/auth/adwords"],
  "data_classification": "confidential",
  "risk_level": "high",
  "tags": ["ads", "google", "campaigns"],
  "semantic_vector": [0.123, 0.456, ...]  // 768-dim embedding
}

4.2 Semantic Discovery

Capabilities are discoverable via natural language queries:

results = await registry.discover(
    query="send conversion events to facebook",
    semantic_search=True,
    top_k=10,
    similarity_threshold=0.5
)

4.3 Agent Budget Tracking

await registry.register_agent(
    agent_id="cell_12",
    name="Optimization Agent",
    capabilities=["google_ads.*", "meta_ads.*"],
    budget_usd=500.0
)
# Warning at 80% budget, block at 95%

5. Rollback System

5.1 Rollback Flow

1. Pre-State Capture: Before any mutation, save entity state
2. Execute Action: Call platform API
3. Post-State Capture: Record resulting state
4. Monitor Performance: Track metrics over time
5. Trigger Rollback: If metrics degrade, restore pre-state
6. Verify Rollback: Confirm entity returned to expected state

5.2 Platform-Specific Rollback

Google Ads: - Bid rollback via campaigns:mutate or adGroups:mutate - Budget rollback via campaignBudgets:mutate - Status rollback via entity status update

Meta Ads: - Campaign status via Graph API POST - Budget via daily_budget update - Ad status via ad endpoint

5.3 Rollback Types

class RollbackType(str, Enum):
    BID_REVERT = "bid_revert"
    BUDGET_REVERT = "budget_revert"
    STATUS_REVERT = "status_revert"
    CREATIVE_REVERT = "creative_revert"
    AUDIENCE_REVERT = "audience_revert"
    FULL_ENTITY_REVERT = "full_entity_revert"

5.4 Atomic Batch Rollback

transaction = await manager.execute_batch_rollback(
    requests=[
        RollbackRequest(action_id="a1", platform="google_ads", ...),
        RollbackRequest(action_id="a2", platform="meta_ads", ...)
    ],
    atomic=True  # All-or-nothing
)
# If any fails, revert successful ones

6. Knowledge Graph Schema

6.1 Node Types

6.2 Edge Types

6.3 ROI Metrics on Edges

@dataclass
class KGEdge:
    value: float = 0.0      # Revenue attributed
    cost: float = 0.0       # Cost attributed
    credit: float = 0.0     # Attribution credit (0-1)
    lift_flag: bool = False # Causal lift indicator

    @property
    def roi(self) -> float:
        return (self.value - self.cost) / self.cost if self.cost > 0 else 0.0

7. Multi-Model Ensemble (Virtuoso)

7.1 Model Assignments

7.2 Routing Logic

# Each MCP tool has a preferred_model tag
tool_governance = {
    "kg_search": {"category": "data_science", "preferred_model": "gemini"},
    "coding_generate": {"category": "coding", "preferred_model": "claude"},
    "creative_generate": {"category": "creative", "preferred_model": "chatgpt"},
    "deploy_cloud_run": {"category": "devops", "preferred_model": "grok"}
}

# Virtuoso router selects based on task category
model = virtuoso_router.select(task_category)

8. API Reference

8.1 Core Endpoints

8.2 SRPVDAL Endpoints

8.3 Policy Engine Endpoints

8.4 Rollback Endpoints

9. MCP Tools Inventory

9.1 By Category

9.2 Tool Governance

Each tool has: - data_classification: public, internal, confidential, pii, financial - risk_level: low, medium, high, destructive - required_scopes: OAuth 2.0 scopes per RFC 8707 - approval_required: boolean for human-in-the-loop

10. Deployment

10.1 Cloud Run Services

10.2 Firestore Collections

10.3 Environment Variables

# SRPVDAL
SRPVDAL_MODE=full  # disabled, dry_run, shadow, canary, ramp, full
SRPVDAL_TRAFFIC_PCT=100

# Google Ads
GOOGLE_ADS_CUSTOMER_ID=xxx
GOOGLE_ADS_DEVELOPER_TOKEN=xxx

# Meta
META_ACCESS_TOKEN=xxx
META_AD_ACCOUNT_ID=xxx
META_PIXEL_ID=xxx

# GA4
GA4_MEASUREMENT_ID=G-xxx
GA4_API_SECRET=xxx

# Feature Flags
ENABLE_SRPVDAL_AUTONOMOUS=true
ENABLE_POLICY_ENGINE=true
ENABLE_KG_BRAIN=true
ENABLE_CONNECTOR_REGISTRY_V2=true
ENABLE_AGENT_SIMULATION=true

11. Security

11.1 Authentication

• OAuth 2.0 with RFC 8707 resource indicators
• Tokens bound to specific tool resources
• Per-tool scope requirements

11.2 Data Classification

11.3 PII Handling

• All email/phone hashed via SHA256 before storage
• CrossPlatformID = SHA256(salt + normalized_email)[:16]
• Consent mode integration (ad_storage, analytics_storage, etc.)
• GDPR: EU endpoints for GA4 (region1.google-analytics.com)
• CCPA: LDU (Limited Data Use) flags for Meta

12. Monitoring

12.1 Key Metrics

12.2 SSE Streaming

Real-time decision stream at /api/v1/srpvdal/stream:

const eventSource = new EventSource('/api/v1/srpvdal/stream');
eventSource.onmessage = (event) => {
    const decision = JSON.parse(event.data);
    // decision: {cycle_id, action, outcome, delta_roi, timestamp}
};

12.3 Audit Trail

Every decision is logged with: - Full input context - Stage outputs (sense, reason, decide, act, learn) - Guardrail check results - API calls with request/response - Pre/post state for rollback

13. Comparison: Blueprint vs MIZ OKI

14. Getting Started

14.1 Quick Start

# Health check
curl https://boss-agent-adk-698171499447.us-central1.run.app/health

# List MCP tools
curl https://boss-agent-adk-698171499447.us-central1.run.app/api/v1/mcp/tools

# Chat
curl -X POST https://boss-agent-adk-698171499447.us-central1.run.app/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is my current ROAS?"}'

14.2 Development

cd miz-oki-adk-agents/boss
pip install -r requirements.v5.3.txt
python boss_agent_core.py

14.3 Deployment

# Boss Agent
gcloud builds submit --config=miz-oki-adk-agents/boss/cloudbuild.v5.yaml --region=us-central1

# Frontend
gcloud builds submit --config=miz-oki-command-center-ui/cloudbuild.yaml --region=global

15. Version History

MIZ OKI Reference Architecture v6.9.1 - January 10, 2026 Exceeds industry standards for autonomous marketing intelligence platforms