Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 14 additions & 55 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,26 +26,11 @@ worker processes open it independently.

## Request path

```mermaid
flowchart LR
C[Client] -->|Bearer key| A[api.py<br/>ThreadingHTTPServer]
A --> K{auth.py<br/>HMAC lookup}
K -->|missing, invalid, revoked| E401[401]
K -->|tenant from key row| R{per-tenant<br/>token bucket}
R -->|empty| E429[429]
R --> T[Tracer span<br/>http.request]
T --> AG[AgentRuntime.ask<br/>react_agent.ReActAgent]
AG -->|every model call| GW[llm_gateway.Gateway<br/>for this tenant]
GW -->|injection check, PII redaction,<br/>cache, output policy| P[GroundedPolicyProvider]
GW -->|blocked| E422[422]
AG -->|tool: search_knowledge_base| KB[KnowledgeBase<br/>tenant index only]
KB --> HR[hybrid_rag.HybridRetriever<br/>BM25 + TF-IDF + HNSW]
HR --> HN[ann_vector_search_library.HNSW]
AG -->|tool: calculator| CALC[react_agent CalculatorTool]
AG -->|optional schema| CG[constrained_generation_library]
T --> TS[(spans table)]
AG --> RESP[answer, citations,<br/>grounded, sources, trace_id]
```
<p align="center">
<img src="architecture/request-path.svg" alt="Request path diagram" width="860">
</p>

<sub>Legend: amber = entry points and external systems, indigo = core logic, green = data and state, blue = validation and control, grey = observability and outputs.</sub>

1. `api.py` reads the `Authorization: Bearer` (or `X-API-Key`) header and calls
`KeyStore.verify`. The tenant comes from the stored key row. Request bodies never carry
Expand All @@ -66,41 +51,15 @@ flowchart LR

## Durable job lifecycle

```mermaid
stateDiagram-v2
[*] --> queued: POST /v1/jobs
queued --> running: claim (BEGIN IMMEDIATE)<br/>lease_owner, lease_expires, lease_token+1
running --> running: heartbeat renews lease
running --> running: step done: ledger row + board snapshot<br/>(one transaction, fenced by lease_token)
running --> running: lease expired, worker dead:<br/>another worker claims, token+1, resumes from board
running --> succeeded: report step checkpointed
running --> failed: critic rejection, step error,<br/>or attempts > max_attempts
succeeded --> [*]
failed --> [*]
```

```mermaid
sequenceDiagram
participant API
participant DB as SQLite
participant WA as Worker A
participant WB as Worker B
API->>DB: INSERT job (queued)
WA->>DB: claim: token=1, expires=now+L
WA->>DB: save plan (blackboard snapshot)
loop each step
WA->>DB: record attempt (q1)
WA->>WA: Orchestrator.attempt_subtask
WA->>DB: save spans
WA->>DB: ledger row q1 + board (only if owner and token=1)
end
Note over WA: SIGKILL. Heartbeats stop.
WB->>DB: claim fails until expires < now
WB->>DB: claim: token=2
WB->>WB: Blackboard.restore(board)
WB->>DB: record attempt (next incomplete step)
WB->>DB: ledger rows, then status=succeeded
```
<p align="center">
<img src="architecture/job-states.svg" alt="Durable job lifecycle diagram" width="483">
</p>

<sub>Legend: amber = entry points and external systems, indigo = core logic, green = data and state, blue = validation and control, grey = observability and outputs.</sub>

<p align="center">
<img src="architecture/job-recovery.svg" alt="Durable job recovery sequence diagram" width="776">
</p>

### Tables

Expand Down
20 changes: 20 additions & 0 deletions docs/architecture/job-recovery.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
sequenceDiagram
participant API
participant DB as SQLite
participant WA as Worker A
participant WB as Worker B
API->>DB: INSERT job (queued)
WA->>DB: claim: token=1, expires=now+L
WA->>DB: save plan (blackboard snapshot)
loop each step
WA->>DB: record attempt (q1)
WA->>WA: Orchestrator.attempt_subtask
WA->>DB: save spans
WA->>DB: ledger row q1 + board (only if owner and token=1)
end
Note over WA: SIGKILL. Heartbeats stop.
WB->>DB: claim fails until expires < now
WB->>DB: claim: token=2
WB->>WB: Blackboard.restore(board)
WB->>DB: record attempt (next incomplete step)
WB->>DB: ledger rows, then status=succeeded
1 change: 1 addition & 0 deletions docs/architecture/job-recovery.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 18 additions & 0 deletions docs/architecture/job-states.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
stateDiagram-v2
direction TB
classDef edge fill:#F59E0B,stroke:#1E293B,color:#1E293B,stroke-width:1px;
classDef core fill:#6366F1,stroke:#1E293B,color:#ffffff,stroke-width:1px;
classDef data fill:#10B981,stroke:#1E293B,color:#ffffff,stroke-width:1px;
classDef control fill:#0EA5E9,stroke:#1E293B,color:#ffffff,stroke-width:1px;
classDef obs fill:#CBD5E1,stroke:#1E293B,color:#1E293B,stroke-width:1px;
[*] --> queued: POST /v1/jobs
queued --> running: claim, lease_token + 1
running --> running: heartbeat, fenced step commit,<br/>reclaim after lease expiry
running --> succeeded: report checkpointed
running --> failed: rejected or out of attempts
succeeded --> [*]
failed --> [*]
class queued data
class running core
class succeeded obs
class failed edge
1 change: 1 addition & 0 deletions docs/architecture/job-states.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions docs/architecture/request-path.mmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
flowchart LR
classDef edge fill:#F59E0B,stroke:#1E293B,color:#1E293B,stroke-width:1px;
classDef core fill:#6366F1,stroke:#1E293B,color:#ffffff,stroke-width:1px;
classDef data fill:#10B981,stroke:#1E293B,color:#ffffff,stroke-width:1px;
classDef control fill:#0EA5E9,stroke:#1E293B,color:#ffffff,stroke-width:1px;
classDef obs fill:#CBD5E1,stroke:#1E293B,color:#1E293B,stroke-width:1px;
subgraph Edge["HTTP edge (api.py)"]
direction TB
C["Client"]:::edge -->|Bearer key| A["api.py<br/>ThreadingHTTPServer"]:::edge
A --> K["auth.py: HMAC key lookup<br/>401 if missing or revoked"]:::control
K -->|tenant from key row| R["per-tenant token bucket<br/>429 when empty"]:::control
end
subgraph Agent["Agent runtime"]
direction TB
T["Tracer span<br/>http.request"]:::obs --> AG["AgentRuntime.ask<br/>ReActAgent loop"]:::core
AG --> RESP["answer, citations,<br/>grounded, trace_id"]:::obs
end
subgraph Calls["Model, tools and retrieval"]
direction TB
GW["llm_gateway.Gateway<br/>422 when blocked"]:::control --> P["GroundedPolicyProvider"]:::edge
CALC["CalculatorTool"]:::core ~~~ CG["constrained_generation<br/>optional schema"]:::control
KB["KnowledgeBase<br/>tenant index only"]:::data --> HR["HybridRetriever<br/>BM25 + TF-IDF + HNSW"]:::core
HR --> HN["ann_vector_search<br/>HNSW"]:::data
P ~~~ CALC
CG ~~~ KB
end
subgraph State["State"]
direction TB
TS[("spans table")]:::data
end
Edge -->|allowed request| Agent
Agent -->|model calls, tools, search| Calls
Agent -.->|spans| State
1 change: 1 addition & 0 deletions docs/architecture/request-path.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading