# 2501pr0ject/ullr-ai architecture

> Architecture diagram of the GitHub repository 2501pr0ject/ullr-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/2501pr0ject/ullr-ai
- Repository: https://github.com/2501pr0ject/ullr-ai

## Overview

Ullr-AI is a security harness for tool-calling agents: the agent routes actions through a deterministic Gateway, which validates and classifies them, obtains signed approval for irreversible actions, records decisions and executes through a separately protected Tools service. Tools state and execution outcomes support reconciliation and evaluation. The README also documents benchmark runs across protected and unprotected conditions with simulated approvers. Relationships below rely on the README and indexed source references; unsampled evaluation internals are represented at directory level.

Main entry points: [`src/ullr_ai/gateway/app.py`](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/app.py) (Gateway API), [`src/ullr_ai/agent/run.py`](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/agent/run.py) (Tool-calling agent), [`src/ullr_ai/gateway/executor_client.py`](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/executor_client.py) (Executor client), [`src/ullr_ai/tools_service/state.py`](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/state.py) (Protected resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_eval["Agent and evaluation"]
  node_agent["Tool-calling agent<br/>[run.py]"]
  node_agent_client["Agent clients<br/>[clients.py]"]
  node_bench["Benchmark runner"]
  node_approvers["Simulated approvers<br/>[approvers.py]"]
  node_evaluation["Evaluation metrics<br/>[evaluate.py]"]
end

subgraph group_gateway["Gateway controls"]
  node_gateway_api["Gateway API<br/>[app.py]"]
  node_schemas["Action schemas<br/>[schemas.py]"]
  node_canonicalization["Canonicalization<br/>[canon.py]"]
  node_policy["Deterministic policy<br/>[policy.py]"]
  node_provenance["Session provenance<br/>[provenance.py]"]
  node_approvals["Approval checks<br/>[approvals.py]"]
  node_signing["Decision signing<br/>[signing.py]"]
  node_budgets["Budget reservations<br/>[budget.py]"]
  node_executor["Executor client<br/>[executor_client.py]"]
  node_reconcile["Execution reconciliation<br/>[reconcile.py]"]
end

subgraph group_tools["Tools execution"]
  node_tools_api["Tools service API<br/>[app.py]"]
  node_executions["Execution handling<br/>[executions.py]"]
  node_tools_state[("Protected resources<br/>[state.py]")]
end

subgraph group_state["Persistence and evidence"]
  node_gateway_db[("Gateway records<br/>[db.py]")]
  node_storage[("SQLite helpers<br/>[storage.py]")]
  node_audit["Audit records<br/>[audit.py]"]
end

node_agent_actor(("Agent runtime"))
node_approver_actor(("Approver"))
node_model(("Language model"))

node_agent_actor -->|"initiates tasks"| node_agent
node_agent -->|"requests responses"| node_model
node_agent -->|"invokes tools"| node_agent_client
node_agent_client -->|"proposes actions"| node_gateway_api
node_gateway_api -->|"validates actions"| node_schemas
node_schemas -->|"hashes actions"| node_canonicalization
node_gateway_api -->|"decides actions"| node_policy
node_gateway_api -->|"tracks reads"| node_provenance
node_gateway_api -->|"checks approvals"| node_approvals
node_approvals -->|"verifies decisions"| node_signing
node_approver_actor -->|"submits decision"| node_gateway_api
node_approver_actor -->|"signs decision"| node_signing
node_gateway_api -->|"reserves budgets"| node_budgets
node_gateway_api -->|"dispatches actions"| node_executor
node_executor -->|"executes requests"| node_tools_api
node_tools_api -->|"handles execution"| node_executions
node_executions -->|"reads and writes"| node_tools_state
node_gateway_api -->|"records actions"| node_gateway_db
node_gateway_db -->|"uses transactions"| node_storage
node_tools_state -->|"uses transactions"| node_storage
node_gateway_api -->|"writes audit events"| node_audit
node_reconcile -->|"checks outcomes"| node_executor
node_bench -.->|"runs episodes"| node_agent
node_bench -.->|"selects conditions"| node_approvers
node_evaluation -.->|"scores outcomes"| node_tools_state

click node_agent "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/agent/run.py"
click node_agent_client "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/agent/clients.py"
click node_bench "https://github.com/2501pr0ject/ullr-ai/tree/main/src/ullr_ai/bench"
click node_approvers "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/bench/approvers.py"
click node_evaluation "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/bench/evaluate.py"
click node_gateway_api "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/app.py"
click node_schemas "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/schemas.py"
click node_canonicalization "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/canon.py"
click node_policy "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/policy.py"
click node_provenance "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/provenance.py"
click node_approvals "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/approvals.py"
click node_signing "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/signing.py"
click node_budgets "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/budget.py"
click node_executor "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/executor_client.py"
click node_reconcile "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/reconcile.py"
click node_tools_api "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/app.py"
click node_executions "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/executions.py"
click node_tools_state "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/state.py"
click node_gateway_db "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/db.py"
click node_storage "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/storage.py"
click node_audit "https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/audit.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_agent_client,node_bench,node_approvers,node_evaluation toneBlue
class node_gateway_api,node_schemas,node_canonicalization,node_policy,node_provenance,node_approvals,node_signing,node_budgets,node_executor,node_reconcile toneAmber
class node_tools_api,node_executions,node_tools_state toneMint
class node_gateway_db,node_storage,node_audit toneRose
class node_agent_actor,node_approver_actor,node_model toneIndigo
```

## Components

### Agent and evaluation

- [Tool-calling agent](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/agent/run.py): `src/ullr_ai/agent/run.py`
- [Agent clients](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/agent/clients.py): `src/ullr_ai/agent/clients.py`
- [Benchmark runner](https://github.com/2501pr0ject/ullr-ai/tree/main/src/ullr_ai/bench): `src/ullr_ai/bench`
- [Simulated approvers](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/bench/approvers.py): `src/ullr_ai/bench/approvers.py`
- [Evaluation metrics](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/bench/evaluate.py): `src/ullr_ai/bench/evaluate.py`

### Gateway controls

- [Gateway API](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/app.py): `src/ullr_ai/gateway/app.py`
- [Action schemas](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/schemas.py): `src/ullr_ai/gateway/schemas.py`
- [Canonicalization](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/canon.py): `src/ullr_ai/gateway/canon.py`
- [Deterministic policy](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/policy.py): `src/ullr_ai/gateway/policy.py`
- [Session provenance](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/provenance.py): `src/ullr_ai/gateway/provenance.py`
- [Approval checks](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/approvals.py): `src/ullr_ai/gateway/approvals.py`
- [Decision signing](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/signing.py): `src/ullr_ai/gateway/signing.py`
- [Budget reservations](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/budget.py): `src/ullr_ai/gateway/budget.py`
- [Executor client](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/executor_client.py): `src/ullr_ai/gateway/executor_client.py`
- [Execution reconciliation](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/reconcile.py): `src/ullr_ai/gateway/reconcile.py`

### Tools execution

- [Tools service API](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/app.py): `src/ullr_ai/tools_service/app.py`
- [Execution handling](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/executions.py): `src/ullr_ai/tools_service/executions.py`
- [Protected resources](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/tools_service/state.py): `src/ullr_ai/tools_service/state.py`

### Persistence and evidence

- [Gateway records](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/db.py): `src/ullr_ai/gateway/db.py`
- [SQLite helpers](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/storage.py): `src/ullr_ai/storage.py`
- [Audit records](https://github.com/2501pr0ject/ullr-ai/blob/main/src/ullr_ai/gateway/audit.py): `src/ullr_ai/gateway/audit.py`

### Other components

- **Agent runtime**
- **Approver**
- **Language model**

## Connections

- Agent runtime → Tool-calling agent: initiates tasks (evidence: `README.md`)
- Tool-calling agent → Language model: requests responses (evidence: `README.md`)
- Tool-calling agent → Agent clients: invokes tools (evidence: `src/ullr_ai/agent/run.py`)
- Agent clients → Gateway API: proposes actions (evidence: `src/ullr_ai/agent/clients.py`)
- Gateway API → Action schemas: validates actions (evidence: `src/ullr_ai/gateway/app.py`)
- Action schemas → Canonicalization: hashes actions (evidence: `src/ullr_ai/gateway/schemas.py`)
- Gateway API → Deterministic policy: decides actions (evidence: `src/ullr_ai/gateway/app.py`)
- Gateway API → Session provenance: tracks reads (evidence: `src/ullr_ai/gateway/app.py`)
- Gateway API → Approval checks: checks approvals (evidence: `src/ullr_ai/gateway/app.py`)
- Approval checks → Decision signing: verifies decisions (evidence: `src/ullr_ai/gateway/approvals.py`)
- Approver → Gateway API: submits decision (evidence: `README.md`)
- Approver → Decision signing: signs decision (evidence: `README.md`)
- Gateway API → Budget reservations: reserves budgets (evidence: `src/ullr_ai/gateway/app.py`)
- Gateway API → Executor client: dispatches actions (evidence: `src/ullr_ai/gateway/app.py`)
- Executor client → Tools service API: executes requests (evidence: `src/ullr_ai/gateway/executor_client.py`)
- Tools service API → Execution handling: handles execution (evidence: `src/ullr_ai/tools_service/app.py`)
- Execution handling → Protected resources: reads and writes (evidence: `src/ullr_ai/tools_service/executions.py`)
- Gateway API → Gateway records: records actions (evidence: `src/ullr_ai/gateway/app.py`)
- Gateway records → SQLite helpers: uses transactions (evidence: `src/ullr_ai/gateway/db.py`)
- Protected resources → SQLite helpers: uses transactions (evidence: `src/ullr_ai/tools_service/state.py`)
- Gateway API → Audit records: writes audit events (evidence: `src/ullr_ai/gateway/app.py`)
- Execution reconciliation → Executor client: checks outcomes (evidence: `src/ullr_ai/gateway/reconcile.py`)
- Benchmark runner → Tool-calling agent: runs episodes
- Benchmark runner → Simulated approvers: selects conditions
- Evaluation metrics → Protected resources: scores outcomes
