# alisonjieli-png/loop-engine architecture

> Architecture diagram of the GitHub repository alisonjieli-png/loop-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alisonjieli-png/loop-engine
- Repository: https://github.com/alisonjieli-png/loop-engine

## Overview

Baltor is the product; Loop Engine is its open engine and Python package. Its documented customer workflow is: a harness searches the reviewed library, receives short references, fetches a chosen item after access is checked, and uses that material in a fresh, bounded step; an independent step can check the result. The library lifecycle runs from source discovery and admission checks through independent review to catalogue publication. The graph includes major documented capabilities and indexed core modules; many service routes and integrations were not excerpted, so their internal call edges are omitted.

Main entry points: [`src/loop_engine/loop/recursive_loop.py`](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/loop/recursive_loop.py) (Recursive Loop), [`src/loop_engine/core/library_ingestion/pipeline.py`](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/pipeline.py) (Ingestion pipeline), [`src/loop_engine/catalog`](https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/catalog) (MCP endpoint), [`src/loop_engine/core/store_serve.py`](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/store_serve.py) (Serving access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Harness delivery"]
  node_harness["Agent harness"]
  node_worker["Container worker"]
end

subgraph group_catalog["Search and delivery"]
  node_mcp["MCP endpoint"]
  node_query["Typed catalogue query<br/>[query.py]"]
  node_storecontract["Store contract<br/>[protocol.py]"]
  node_sqlstore[("SQLite catalogue<br/>[sqlite_store.py]")]
  node_storeserve["Serving access<br/>[store_serve.py]"]
  node_facets["Facet filtering<br/>[facets.py]"]
  node_catalogue[("Published catalogue")]
end

subgraph group_library["Library lifecycle"]
  node_ingest["Ingestion pipeline<br/>[pipeline.py]"]
  node_checks["Admission checks<br/>[pipeline_checks.py]"]
  node_provenance["Provenance records<br/>[provenance.py]"]
  node_recordrules["Record validation<br/>[record_rules.py]"]
  node_transport["Bounded HTTPS<br/>[https_transport.py]"]
  node_requestlog["Request log<br/>[request_log.py]"]
  node_candidate_review["Independent review<br/>[engines.py]"]
end

subgraph group_engine["Loop runtime"]
  node_loop["Recursive Loop<br/>[recursive_loop.py]"]
  node_decisions["Decision engines"]
  node_similarity["Task similarity"]
  node_question["Question engine<br/>[question_engine.py]"]
  node_proof["Engine proof"]
end

subgraph group_discovery["Source discovery"]
  node_radar["Knowledge radar<br/>[pipeline.py]"]
  node_radar_network["Network discovery<br/>[engines_network.py]"]
  node_radar_engines["Radar engines<br/>[engines.py]"]
  node_radar_records["Discovery records<br/>[records.py]"]
  node_outside_import["Outside-material import"]
end

node_customer(("Customer"))

node_customer -->|"starts task"| node_harness
node_harness -->|"searches library"| node_mcp
node_mcp -.->|"queries catalogue"| node_query
node_query -.->|"reads records"| node_sqlstore
node_mcp -->|"returns references"| node_harness
node_harness -->|"downloads choice"| node_storeserve
node_storeserve -->|"checks access"| node_catalogue
node_storeserve -->|"delivers bytes"| node_harness
node_harness -->|"runs in"| node_worker
node_ingest -->|"runs checks"| node_checks
node_ingest -.->|"records origins"| node_provenance
node_ingest -.->|"validates records"| node_recordrules
node_transport -->|"records requests"| node_requestlog
node_radar -->|"collects sources"| node_radar_engines
node_radar -->|"records findings"| node_radar_records
node_radar_network -->|"uses transport"| node_transport
node_outside_import -->|"stages material"| node_ingest
node_candidate_review -->|"approves admission"| node_catalogue
node_catalogue -->|"serves library"| node_mcp
node_harness -->|"runs step"| node_loop
node_loop -.->|"uses decisions"| node_decisions
node_loop -.->|"checks similarity"| node_similarity
node_loop -.->|"forms questions"| node_question
node_loop -.->|"independent check"| node_proof

click node_worker "https://github.com/alisonjieli-png/loop-engine/tree/main/containers/worker"
click node_mcp "https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/catalog"
click node_query "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/catalog/query.py"
click node_storecontract "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/catalog/protocol.py"
click node_sqlstore "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/catalog/stores/sqlite_store.py"
click node_storeserve "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/store_serve.py"
click node_facets "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/facets.py"
click node_catalogue "https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/catalog"
click node_ingest "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/pipeline.py"
click node_checks "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/pipeline_checks.py"
click node_provenance "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/provenance.py"
click node_recordrules "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/record_rules.py"
click node_transport "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/https_transport.py"
click node_requestlog "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/request_log.py"
click node_candidate_review "https://github.com/alisonjieli-png/loop-engine/blob/main/tools/candidate_review/engines.py"
click node_radar "https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/pipeline.py"
click node_radar_network "https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/engines_network.py"
click node_radar_engines "https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/engines.py"
click node_radar_records "https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/records.py"
click node_outside_import "https://github.com/alisonjieli-png/loop-engine/blob/main/tools/ingest_outside_material.py"
click node_loop "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/loop/recursive_loop.py"
click node_decisions "https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/core/decisions"
click node_similarity "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/task_similarity_engine.py"
click node_question "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/strings/question_engine.py"
click node_proof "https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/code_nodes/core_engine_proof.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_harness,node_worker toneBlue
class node_mcp,node_query,node_storecontract,node_sqlstore,node_storeserve,node_facets,node_catalogue toneAmber
class node_ingest,node_checks,node_provenance,node_recordrules,node_transport,node_requestlog,node_candidate_review toneMint
class node_loop,node_decisions,node_similarity,node_question,node_proof toneRose
class node_radar,node_radar_network,node_radar_engines,node_radar_records,node_outside_import,node_customer toneIndigo
```

## Components

### Harness delivery

- **Agent harness**
- [Container worker](https://github.com/alisonjieli-png/loop-engine/tree/main/containers/worker): `containers/worker`

### Search and delivery

- [MCP endpoint](https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/catalog): `src/loop_engine/catalog`
- [Typed catalogue query](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/catalog/query.py): `src/loop_engine/catalog/query.py`
- [Store contract](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/catalog/protocol.py): `src/loop_engine/catalog/protocol.py`
- [SQLite catalogue](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/catalog/stores/sqlite_store.py): `src/loop_engine/catalog/stores/sqlite_store.py`
- [Serving access](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/store_serve.py): `src/loop_engine/core/store_serve.py`
- [Facet filtering](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/facets.py): `src/loop_engine/core/facets.py`
- [Published catalogue](https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/catalog): `src/loop_engine/catalog`

### Library lifecycle

- [Ingestion pipeline](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/pipeline.py): `src/loop_engine/core/library_ingestion/pipeline.py`
- [Admission checks](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/pipeline_checks.py): `src/loop_engine/core/library_ingestion/pipeline_checks.py`
- [Provenance records](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/provenance.py): `src/loop_engine/core/library_ingestion/provenance.py`
- [Record validation](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/record_rules.py): `src/loop_engine/core/library_ingestion/record_rules.py`
- [Bounded HTTPS](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/https_transport.py): `src/loop_engine/core/library_ingestion/https_transport.py`
- [Request log](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/library_ingestion/request_log.py): `src/loop_engine/core/library_ingestion/request_log.py`
- [Independent review](https://github.com/alisonjieli-png/loop-engine/blob/main/tools/candidate_review/engines.py): `tools/candidate_review/engines.py`

### Loop runtime

- [Recursive Loop](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/loop/recursive_loop.py): `src/loop_engine/loop/recursive_loop.py`
- [Decision engines](https://github.com/alisonjieli-png/loop-engine/tree/main/src/loop_engine/core/decisions): `src/loop_engine/core/decisions`
- [Task similarity](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/core/task_similarity_engine.py): `src/loop_engine/core/task_similarity_engine.py`
- [Question engine](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/strings/question_engine.py): `src/loop_engine/strings/question_engine.py`
- [Engine proof](https://github.com/alisonjieli-png/loop-engine/blob/main/src/loop_engine/code_nodes/core_engine_proof.py): `src/loop_engine/code_nodes/core_engine_proof.py`

### Source discovery

- [Knowledge radar](https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/pipeline.py): `tools/knowledge_radar/pipeline.py`
- [Network discovery](https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/engines_network.py): `tools/knowledge_radar/engines_network.py`
- [Radar engines](https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/engines.py): `tools/knowledge_radar/engines.py`
- [Discovery records](https://github.com/alisonjieli-png/loop-engine/blob/main/tools/knowledge_radar/records.py): `tools/knowledge_radar/records.py`
- [Outside-material import](https://github.com/alisonjieli-png/loop-engine/blob/main/tools/ingest_outside_material.py): `tools/ingest_outside_material.py`

### Other components

- **Customer**

## Connections

- Customer → Agent harness: starts task (evidence: `README.md`)
- Agent harness → MCP endpoint: searches library (evidence: `README.md`)
- MCP endpoint → Typed catalogue query: queries catalogue (evidence: `src/loop_engine/catalog/stores/sqlite_store.py`)
- Typed catalogue query → SQLite catalogue: reads records (evidence: `src/loop_engine/catalog/stores/sqlite_store.py`)
- MCP endpoint → Agent harness: returns references (evidence: `README.md`)
- Agent harness → Serving access: downloads choice (evidence: `README.md`)
- Serving access → Published catalogue: checks access (evidence: `README.md`)
- Serving access → Agent harness: delivers bytes (evidence: `README.md`)
- Agent harness → Container worker: runs in (evidence: `README.md`)
- Ingestion pipeline → Admission checks: runs checks (evidence: `src/loop_engine/core/library_ingestion/pipeline_checks.py`)
- Ingestion pipeline → Provenance records: records origins
- Ingestion pipeline → Record validation: validates records
- Bounded HTTPS → Request log: records requests (evidence: `src/loop_engine/core/library_ingestion/https_transport.py`)
- Knowledge radar → Radar engines: collects sources (evidence: `tools/knowledge_radar/pipeline.py`)
- Knowledge radar → Discovery records: records findings (evidence: `tools/knowledge_radar/pipeline.py`)
- Network discovery → Bounded HTTPS: uses transport (evidence: `tools/knowledge_radar/engines_network.py`)
- Outside-material import → Ingestion pipeline: stages material (evidence: `tools/ingest_outside_material.py`)
- Independent review → Published catalogue: approves admission (evidence: `README.md`)
- Published catalogue → MCP endpoint: serves library (evidence: `README.md`)
- Agent harness → Recursive Loop: runs step (evidence: `README.md`)
- Recursive Loop → Decision engines: uses decisions
- Recursive Loop → Task similarity: checks similarity (evidence: `src/loop_engine/core/task_similarity_engine.py`)
- Recursive Loop → Question engine: forms questions
- Recursive Loop → Engine proof: independent check (evidence: `src/loop_engine/code_nodes/core_engine_proof.py`)