Architecture & Patterns

Core Architecture: The Physics-Respecting Stack

Three-layer sandwich where deterministic code wraps probabilistic AI:

┌─────────────────────────────────────┐
│  Execution Layer (Deterministic)    │  ← Code handles: auth, params, retries
├─────────────────────────────────────┤
│  Reasoning Layer (Probabilistic)    │  ← LLM handles: decisions, planning
├─────────────────────────────────────┤
│  Persistence Layer (Durable)        │  ← Redis + blob storage for state
└─────────────────────────────────────┘

Key insight: LLM decides what to do; code handles how to do it. This separation cuts hallucination rates by 60-80%.

Checkpoint-Every-Turn Pattern

┌──────────┐    ┌──────────┐    ┌──────────┐
│ Observe  │───▶│  Orient  │───▶│  Decide  │
└──────────┘    └──────────┘    └──────────┘
                                     │
                                     ▼
                              ┌──────────┐
                              │   Act    │
                              └──────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
              ┌──────────┐    ┌──────────┐    ┌──────────┐
              │  Redis   │    │   Blob   │    │   Next   │
              │ (fast)   │    │ (durable)│    │   Turn   │
              └──────────┘    └──────────┘    └──────────┘

Dual-write: Fast path (Redis) for quick recovery, blob storage for crash resilience. Pod dies → new pod loads from Redis → continues seamlessly.

---

State Re-Hydration (Inheritance Graph)

For multi-step workflows with dependencies:

Step 1 (Auth) ─────────┐
                       ├───▶ Step 4 (Report)
Step 2 (Fetch) ────────┤
                       │
Step 3 (Validate) ─────┘

Each step inherits:

1. Previous outputs from all upstream steps
2. Discovered variables (auth tokens, IDs, etc.)
3. Compressed history summaries

Implementation: Redis hashes keyed by context:{workflow_id}:{step_id}

---

Entropy Management Pipeline

Raw Input ──▶ Sanitize ──▶ Compress ──▶ Evict ──▶ Context Window
    │            │            │           │
    │        Strip stack  Summarize    Drop P3,
    │        traces to    old logs     then P2
    │        root cause   to 1 para    by age
    │
    └─── Measure entropy score after each step

Trigger: When context > 80% capacity OR entropy score > 0.7

---

Parameter Injection Safety Net

LLM Output: "Call fetch_patient()"
           (forgot auth_token param)
                    │
                    ▼
         ┌─────────────────────┐
         │ Execution Layer     │
         │                     │
         │ 1. Parse function   │
         │ 2. Check signature  │
         │ 3. Auto-inject from │◀── state.variables["auth_token"]
         │    state if missing │
         │ 4. Execute          │
         └─────────────────────┘
                    │
                    ▼
            Complete API call
            (with auth token)

Injectable params: auth_token, base_url, workflow_id, step_id—anything deterministic.

---

Key Design Decisions

1. AP over CP in distributed agent meshes—agents operate autonomously, accept eventual consistency
2. Temperature varies by task: 0.2 for execution, 0.5 for recovery, 0.7 for planning
3. Retries transform math: 3 retries converts 2% error → 0.0008% error per step
4. Context budget: usable = total - system_prompt - output_reserve (typically ~90% of advertised)
5. Compression over truncation: Never silently drop; always summarize and log what was compressed

---

Architecture & Patterns — FikAi notebook for The Physics of AI Engineering.