Skip to content

Commit 4b674ae

Browse files
HaibaraAi137HaibaraAi137
committed
aa
1 parent 8935939 commit 4b674ae

36 files changed

Lines changed: 2544 additions & 572 deletions

‎README.md‎

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -97,24 +97,49 @@ HalfSeed talks to any OpenAI-compatible `/chat/completions` endpoint, so you can
9797

9898
Every option only needs you to edit `.env`. See [`.env.example`](.env.example) for ready-to-uncomment templates.
9999

100-
### Try without an API key
100+
### Five-minute smoke test (no API key)
101101

102-
The CLI ships with a deterministic offline backend so you can see the workflow run end-to-end with no LLM calls:
102+
The CLI ships with a deterministic offline backend that runs the full
103+
project pipeline (agents → curator → writer → presentation) using
104+
canned responses, so you can see the shape of the output before
105+
spending a token. This produces a real project on disk:
103106

104107
```bash
105-
python -m halfseed --offline "Can a scalar EFT preserve shift symmetry after a derivative interaction is added?"
106-
```
108+
mkdir my-runs && cd my-runs
109+
python -m halfseed init demo "Can a scalar EFT preserve shift symmetry?"
110+
python -m halfseed run demo --offline --no-latex-gate
107111

108-
In the web UI, check **"Offline backend"** on the Run tab.
112+
# What just happened? Read the briefing the Director wrote:
113+
python -m halfseed brief demo
109114

110-
## How to use it
115+
# The paper draft is in runs/demo/paper.tex (offline mode fills it
116+
# with deterministic placeholder prose so you can see the structure).
117+
ls runs/demo/
118+
```
111119

112-
1. **Create a project** with your research question (English or Chinese).
113-
2. Optionally edit **architecture** — drag agents around, change their missions, disable any you don't want.
114-
3. **Run an iteration**. The architecture graph highlights the active agent; the event stream shows handoffs in real time.
115-
4. **Review artifacts**: approve the good ones, reject the wrong ones (this teaches the Director to avoid dead ends next iteration).
116-
5. **Write directives** for the next round in plain text. They get fed to the Director on the next run.
117-
6. **Compile the PDF** from the Paper or PDF tab. Edit it directly inside `% PI-LOCK BEGIN ... % PI-LOCK END` regions and your edits survive future iterations.
120+
The numbers in `briefing.md` come from offline canned data — confidence
121+
scores, artifact counts, and the "Stop reason" are not real research
122+
output. The point is to verify the install works and to show what
123+
artifact files end up where.
124+
125+
> **Note: the legacy one-shot command** `python -m halfseed --offline "<question>"`
126+
> prints a single markdown memo to stdout *without* creating a project
127+
> and *without* running the iteration loop. It exists for quick sanity
128+
> checks; for anything beyond that, use the `init` + `run` flow above.
129+
130+
When you're ready to run with a real model, drop the `--offline` flag,
131+
add your API key to `.env`, and re-run `halfseed run demo`. The project
132+
on disk is the same; only the agent backend changes.
133+
134+
## How to use it (web UI)
135+
136+
1. Start the server (`./start.sh`) and open <http://127.0.0.1:5173/>.
137+
2. **Create a project** with your research question (English or Chinese).
138+
3. Optionally edit **architecture** — drag agents around, change their missions, disable any you don't want. The "Run iteration" button is disabled if the graph has structural errors (cycle, missing required role, etc.) so you find out before launching.
139+
4. **Run an iteration**. The architecture graph highlights the active agent; the event stream shows handoffs in real time.
140+
5. **Review artifacts**: approve the good ones, reject the wrong ones (this teaches the Director to avoid dead ends next iteration).
141+
6. **Write directives** for the next round in plain text. They get fed to the Director on the next run.
142+
7. **Compile the PDF** from the Paper or PDF tab. Edit it directly inside `% PI-LOCK BEGIN ... % PI-LOCK END` regions and your edits survive future iterations.
118143

119144
## Configuration
120145

‎docs/architecture.md‎

Lines changed: 116 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,145 @@
11
# Architecture
22

3-
HalfSeed separates orchestration from model access.
3+
HalfSeed separates orchestration from model access. This document is
4+
the high-level tour; the precise data and execution model lives in
5+
[graph-workflow-spec.md](graph-workflow-spec.md).
46

5-
## Workflow
7+
## Two layers
68

7-
1. `Principal` converts the human question into a structured research brief.
8-
2. `Analytical`, `Numerical`, and `Literature` agents work from the same brief.
9-
3. `Skeptic` critiques every artifact and adds failure modes.
10-
4. `Analytical` and `Numerical` perform one revision pass using the critiques.
11-
5. `Curator` filters and ranks artifacts with a deterministic budget guard.
12-
6. `Presentation` produces a concise research memo.
13-
7. `Principal` performs a final user-facing pass.
9+
```
10+
┌────────────────────────────────────────────────────────────┐
11+
│ Orchestration (this repo) │
12+
│ • ProjectArchitecture: a DAG of agents and edges │
13+
│ • Director: plans iterations and decides when to stop │
14+
│ • Workflow: turns the graph into LLM calls per iteration │
15+
└─────────────────────────┬──────────────────────────────────┘
16+
│ ChatBackend protocol
17+
┌─────────────────────────▼──────────────────────────────────┐
18+
│ Model access │
19+
│ • DeepSeekChatBackend (live) │
20+
│ • OpenAI / Anthropic via ProviderRouter (live) │
21+
│ • RuleBasedBackend (offline, deterministic for tests) │
22+
└────────────────────────────────────────────────────────────┘
23+
```
24+
25+
The boundary is the `ChatBackend` protocol — anything below it is
26+
"how to talk to a model", anything above it is "what to ask it".
27+
28+
## Workflow shape
29+
30+
A project's workflow is a **graph of agents** edited in the web UI.
31+
The graph is a DAG; the system enforces this at validation time.
32+
33+
The default architecture looks like:
34+
35+
```
36+
Director
37+
├─→ Analytical (specialist) ─┐
38+
├─→ Numerical (specialist) ─┼─→ Skeptic ─→ Curator ─→ Presentation
39+
└─→ Literature (specialist) ─┘
40+
```
41+
42+
Plus `Principal`, which sits at the head of the graph (it issues the
43+
brief into the graph) and is also called by the runtime *outside* the
44+
graph for the final user-facing answer.
45+
46+
### What edges mean
1447

15-
## Why This Shape
48+
A → B means exactly: **"A's output flows into B's input on this iteration."**
49+
Edges have no labels, no payload fields, no "purpose" — wires are wires;
50+
all behavior is on the nodes (each node's `mission` and `output_contract`
51+
free-text fields). See [graph-workflow-spec.md §3](graph-workflow-spec.md)
52+
for the rationale and §9 for why edge-level prompts were rejected.
1653

17-
The design avoids unbounded group chat. Every internal message is converted into
18-
a `ResearchArtifact`, and the curator has a hard `max_items` budget. This makes
19-
agent output reviewable, testable, and easier to visualize later.
54+
When the user removes an edge in the architecture editor, the runtime
55+
genuinely stops flowing those artifacts to the downstream node — see
56+
`runtime/edge_filter.py`.
57+
58+
### What's outside the graph
59+
60+
Some behaviors are runtime mechanisms, not graph-expressible:
61+
62+
- **Iteration loop.** The graph is a DAG; multi-iteration loops are
63+
the Director re-running the whole graph for another round. The
64+
Director's `should_stop` decision sits outside the graph.
65+
- **Attack-vector market.** When ≥2 specialists share an upstream,
66+
the runtime auto-runs a "pick distinct angles" protocol before
67+
their layer executes.
68+
- **Cross-iteration context.** `prior_iteration_summary`,
69+
`open_threads`, `rejected_claims`, the artifact pool — auto-injected
70+
into every node's prompt, not drawn as edges.
71+
- **Side effects.** Numerical sandbox runs and Writer's edits to
72+
`paper.tex` happen as post-processing hooks attached to the
73+
relevant role kinds.
74+
75+
Spec [§5](graph-workflow-spec.md) covers each of these in detail.
76+
77+
## Why this shape
78+
79+
The design avoids unbounded group chat. Every internal message is
80+
converted into a `ResearchArtifact`, and the curator has a hard
81+
`max_items` budget. Output is reviewable, testable, and visualizable.
82+
83+
Validation rules (cycles, duplicate singletons, unreachable specialists,
84+
etc.) run server-side and surface in the architecture editor; the
85+
"Run iteration" button is disabled when the graph has errors. See
86+
`architecture_validate.py` and spec §6 for the full rule list.
2087

2188
## Tools
2289

2390
HalfSeed currently has two non-visual tools:
2491

25-
- `ArxivSearchClient` retrieves arXiv candidates and passes them as context to the Literature agent when `--literature-search` is enabled.
26-
- `NumericalSandbox` runs project-owned numerical checks. The first built-in routine performs an RK4 smoke check for harmonic oscillator stability questions.
27-
28-
The numerical sandbox does not run arbitrary model-written Python. New routines
29-
should be explicit project code with tests.
92+
- `ArxivSearchClient` retrieves arXiv candidates and feeds them to
93+
whichever specialist matches the literature role kind when
94+
`--literature-search` is enabled.
95+
- `NumericalSandbox` runs project-owned numerical checks. The first
96+
built-in routine performs an RK4 smoke check for harmonic-oscillator
97+
stability questions. It does not run arbitrary model-written code;
98+
the sandbox that *does* run code artifacts is in `qa/sandbox.py` and
99+
is invoked as a Numerical-role side effect.
30100

31101
## Stability
32102

33-
Live LLM calls are not trusted to always return perfect JSON. The workflow:
103+
Live LLM calls are not trusted to always return perfect JSON. The
104+
workflow:
34105

35106
- requests JSON mode from the backend;
36107
- retries malformed JSON once with a compact regeneration prompt;
37-
- normalizes common schema variations such as list-style specialist questions;
38-
- falls back to low-confidence artifacts when an internal specialist still fails;
39-
- retries transient DeepSeek HTTP errors such as 429 and 5xx responses.
108+
- normalizes common schema variations (e.g. list-style specialist
109+
questions);
110+
- falls back to low-confidence artifacts when an internal specialist
111+
still fails;
112+
- retries transient HTTP errors such as 429 and 5xx.
40113

41114
## Persistence
42115

43-
`RunStore` writes both structured JSON and rendered Markdown for each run. The
44-
CLI enables this with `--save-run`, using `runs/` by default.
116+
`ProjectStore` writes structured JSON for each iteration plus a
117+
rendered Markdown briefing. The CLI also exposes `RunStore` for the
118+
older one-shot `run()` path with `--save-run`.
45119

46-
## Backend Boundary
120+
## Backend boundary
47121

48-
All agents depend on `ChatBackend`. The current live backend is
49-
`DeepSeekChatBackend`, but tests and offline demos use `RuleBasedBackend`.
50-
51-
Future backend additions should implement:
122+
All agents depend on `ChatBackend`:
52123

53124
```python
54125
class ChatBackend(Protocol):
55126
def complete(self, request: ChatRequest) -> ChatResponse:
56127
...
57128
```
58129

59-
## Planned Extensions
60-
61-
- Add persistent run storage.
62-
- Add graph visualization for curator output.
63-
- Add code execution tools for numerical checks.
64-
- Add retrieval-backed literature search.
65-
- Add role-specific model routing while keeping shared V4 as the default.
130+
The current live backends are `DeepSeekChatBackend` and the OpenAI/
131+
Anthropic adapters routed via `ProviderRouter`. Tests and offline
132+
demos use `RuleBasedBackend`. New backends only need to implement
133+
the protocol.
134+
135+
## Pointers
136+
137+
| topic | start here |
138+
|---|---|
139+
| precise graph model + execution algorithm | [graph-workflow-spec.md](graph-workflow-spec.md) |
140+
| validator rules | `architecture_validate.py` + spec §6 |
141+
| edge-driven artifact filtering | `runtime/edge_filter.py` |
142+
| graph executor (topo sort, layered run) | `runtime/graph_executor.py` |
143+
| role definitions and singleton constraints | `agents/roles.py` |
144+
| Director (iteration planner) | `agents/director.py` |
145+
| paper rendering | `publish/paper.py` and `publish/paper_edits.py` |

0 commit comments

Comments
 (0)