# isb333/crucible architecture

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

- Interactive diagram: https://gitdiagram.com/isb333/crucible
- Repository: https://github.com/isb333/crucible

## Overview

Crucible is a verifier-grounded search engine: a user supplies a task with editable regions, and independent LLM workers iteratively edit candidate artifacts until a verifier accepts one or the run budget is exhausted. The orchestrator manages workers and rechecks a prospective winner in a fresh sandbox; integrity checks guard against altered frozen regions and gaming. Results, episodes, artifact versions, and model reasoning are recorded in SQLite for later inspection. The README also documents scored optimization and code, proof, and chemistry verifier capabilities. Wiring for unsampled modules is shown only where documented or supported by the tree.

Main entry points: [`crucible/orchestrator.py`](https://github.com/isb333/crucible/blob/main/crucible/orchestrator.py) (Worker orchestration), [`crucible/worker.py`](https://github.com/isb333/crucible/blob/main/crucible/worker.py) (Worker loop), [`crucible/verifiers`](https://github.com/isb333/crucible/tree/main/crucible/verifiers) (Verifier implementations), [`crucible/cli.py`](https://github.com/isb333/crucible/blob/main/crucible/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Tasks"]
  node_cli["CLI<br/>[cli.py]"]
  node_sdk["SDK entry<br/>[__init__.py]"]
  node_task["Task definition<br/>[task.py]"]
  node_artifact["Editable artifact<br/>[artifact.py]"]
end

subgraph group_search["Search Engine"]
  node_orchestrator["Worker orchestration<br/>[orchestrator.py]"]
  node_worker["Worker loop<br/>[worker.py]"]
  node_edits["Region edits<br/>[edits.py]"]
  node_budgets["Search budgets<br/>[budgets.py]"]
end

subgraph group_checks["Verification and Integrity"]
  node_verdict["Verdict contract<br/>[verify.py]"]
  node_verifiers["Verifier implementations"]
  node_integrity["Integrity gate<br/>[integrity.py]"]
  node_sandbox["Execution sandbox<br/>[sandbox.py]"]
end

subgraph group_models["Models and Advice"]
  node_llm["LLM session API<br/>[llm.py]"]
  node_providers["Model providers<br/>[providers.py]"]
  node_advisor["Advisor<br/>[advisor.py]"]
end

subgraph group_records["Run Records"]
  node_store[("Run store<br/>[store.py]")]
  node_reasoning["Reasoning inspection<br/>[cli.py]"]
end

node_user(("Task author"))
node_model_service{{"LLM services"}}

node_user -->|"starts run"| node_cli
node_cli -->|"invokes"| node_sdk
node_sdk -->|"starts search"| node_orchestrator
node_orchestrator -->|"loads task"| node_task
node_orchestrator -->|"builds initial"| node_artifact
node_orchestrator -->|"dispatches workers"| node_worker
node_orchestrator -->|"configures limits"| node_budgets
node_orchestrator -->|"creates checks"| node_integrity
node_worker -->|"requests turns"| node_llm
node_worker -->|"applies edits"| node_edits
node_worker -->|"checks candidate"| node_verifiers
node_worker -->|"checks edits"| node_integrity
node_worker -->|"records episodes"| node_store
node_orchestrator -->|"rechecks winner"| node_verifiers
node_verifiers -->|"returns verdict"| node_verdict
node_verifiers -->|"runs checks"| node_sandbox
node_integrity -->|"fresh reverify"| node_sandbox
node_orchestrator -->|"creates workspaces"| node_sandbox
node_orchestrator -->|"creates sessions"| node_providers
node_providers -->|"implements sessions"| node_llm
node_providers -->|"sends prompts"| node_model_service
node_worker -.->|"consults optionally"| node_advisor
node_advisor -.->|"requests advice"| node_model_service
node_cli -->|"displays history"| node_reasoning
node_reasoning -->|"reads history"| node_store
node_orchestrator -->|"records run events"| node_store

click node_cli "https://github.com/isb333/crucible/blob/main/crucible/cli.py"
click node_sdk "https://github.com/isb333/crucible/blob/main/crucible/__init__.py"
click node_task "https://github.com/isb333/crucible/blob/main/crucible/task.py"
click node_artifact "https://github.com/isb333/crucible/blob/main/crucible/artifact.py"
click node_orchestrator "https://github.com/isb333/crucible/blob/main/crucible/orchestrator.py"
click node_worker "https://github.com/isb333/crucible/blob/main/crucible/worker.py"
click node_edits "https://github.com/isb333/crucible/blob/main/crucible/edits.py"
click node_budgets "https://github.com/isb333/crucible/blob/main/crucible/budgets.py"
click node_verdict "https://github.com/isb333/crucible/blob/main/crucible/verify.py"
click node_verifiers "https://github.com/isb333/crucible/tree/main/crucible/verifiers"
click node_integrity "https://github.com/isb333/crucible/blob/main/crucible/integrity.py"
click node_sandbox "https://github.com/isb333/crucible/blob/main/crucible/sandbox.py"
click node_llm "https://github.com/isb333/crucible/blob/main/crucible/llm.py"
click node_providers "https://github.com/isb333/crucible/blob/main/crucible/providers.py"
click node_advisor "https://github.com/isb333/crucible/blob/main/crucible/advisor.py"
click node_store "https://github.com/isb333/crucible/blob/main/crucible/store.py"
click node_reasoning "https://github.com/isb333/crucible/blob/main/crucible/cli.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_cli,node_sdk,node_task,node_artifact toneBlue
class node_orchestrator,node_worker,node_edits,node_budgets toneAmber
class node_verdict,node_verifiers,node_integrity,node_sandbox toneMint
class node_llm,node_providers,node_advisor,node_user toneRose
class node_store,node_reasoning,node_model_service toneIndigo
```

## Components

### Entry and Tasks

- [CLI](https://github.com/isb333/crucible/blob/main/crucible/cli.py): `crucible/cli.py`
- [SDK entry](https://github.com/isb333/crucible/blob/main/crucible/__init__.py): `crucible/__init__.py`
- [Task definition](https://github.com/isb333/crucible/blob/main/crucible/task.py): `crucible/task.py`
- [Editable artifact](https://github.com/isb333/crucible/blob/main/crucible/artifact.py): `crucible/artifact.py`

### Search Engine

- [Worker orchestration](https://github.com/isb333/crucible/blob/main/crucible/orchestrator.py): `crucible/orchestrator.py`
- [Worker loop](https://github.com/isb333/crucible/blob/main/crucible/worker.py): `crucible/worker.py`
- [Region edits](https://github.com/isb333/crucible/blob/main/crucible/edits.py): `crucible/edits.py`
- [Search budgets](https://github.com/isb333/crucible/blob/main/crucible/budgets.py): `crucible/budgets.py`

### Verification and Integrity

- [Verdict contract](https://github.com/isb333/crucible/blob/main/crucible/verify.py): `crucible/verify.py`
- [Verifier implementations](https://github.com/isb333/crucible/tree/main/crucible/verifiers): `crucible/verifiers`
- [Integrity gate](https://github.com/isb333/crucible/blob/main/crucible/integrity.py): `crucible/integrity.py`
- [Execution sandbox](https://github.com/isb333/crucible/blob/main/crucible/sandbox.py): `crucible/sandbox.py`

### Models and Advice

- [LLM session API](https://github.com/isb333/crucible/blob/main/crucible/llm.py): `crucible/llm.py`
- [Model providers](https://github.com/isb333/crucible/blob/main/crucible/providers.py): `crucible/providers.py`
- [Advisor](https://github.com/isb333/crucible/blob/main/crucible/advisor.py): `crucible/advisor.py`

### Run Records

- [Run store](https://github.com/isb333/crucible/blob/main/crucible/store.py): `crucible/store.py`
- [Reasoning inspection](https://github.com/isb333/crucible/blob/main/crucible/cli.py): `crucible/cli.py`

### Other components

- **Task author**
- **LLM services**

## Connections

- Task author → CLI: starts run
- CLI → SDK entry: invokes
- SDK entry → Worker orchestration: starts search
- Worker orchestration → Task definition: loads task
- Worker orchestration → Editable artifact: builds initial
- Worker orchestration → Worker loop: dispatches workers
- Worker orchestration → Search budgets: configures limits
- Worker orchestration → Integrity gate: creates checks
- Worker loop → LLM session API: requests turns
- Worker loop → Region edits: applies edits
- Worker loop → Verifier implementations: checks candidate
- Worker loop → Integrity gate: checks edits
- Worker loop → Run store: records episodes
- Worker orchestration → Verifier implementations: rechecks winner
- Verifier implementations → Verdict contract: returns verdict
- Verifier implementations → Execution sandbox: runs checks
- Integrity gate → Execution sandbox: fresh reverify
- Worker orchestration → Execution sandbox: creates workspaces
- Worker orchestration → Model providers: creates sessions
- Model providers → LLM session API: implements sessions
- Model providers → LLM services: sends prompts
- Worker loop → Advisor: consults optionally
- Advisor → LLM services: requests advice
- CLI → Reasoning inspection: displays history
- Reasoning inspection → Run store: reads history
- Worker orchestration → Run store: records run events