pyharnx 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pyharnx-0.1.0/LICENSE +21 -0
- pyharnx-0.1.0/PKG-INFO +269 -0
- pyharnx-0.1.0/README.md +238 -0
- pyharnx-0.1.0/pyharnx/__init__.py +0 -0
- pyharnx-0.1.0/pyharnx/agent/__init__.py +24 -0
- pyharnx-0.1.0/pyharnx/agent/agent.py +210 -0
- pyharnx-0.1.0/pyharnx/agent/loop.py +783 -0
- pyharnx-0.1.0/pyharnx/agent/types.py +275 -0
- pyharnx-0.1.0/pyharnx/cli/__init__.py +5 -0
- pyharnx-0.1.0/pyharnx/cli/approval.py +119 -0
- pyharnx-0.1.0/pyharnx/cli/commands.py +312 -0
- pyharnx-0.1.0/pyharnx/cli/export.html +777 -0
- pyharnx-0.1.0/pyharnx/cli/export.py +634 -0
- pyharnx-0.1.0/pyharnx/cli/json_sink.py +31 -0
- pyharnx-0.1.0/pyharnx/cli/main.py +545 -0
- pyharnx-0.1.0/pyharnx/cli/renderers.py +734 -0
- pyharnx-0.1.0/pyharnx/cli/terminal.py +860 -0
- pyharnx-0.1.0/pyharnx/cli/usage.py +203 -0
- pyharnx-0.1.0/pyharnx/config.py +1050 -0
- pyharnx-0.1.0/pyharnx/llm/__init__.py +34 -0
- pyharnx-0.1.0/pyharnx/llm/catalog.toml +373 -0
- pyharnx-0.1.0/pyharnx/llm/events.py +107 -0
- pyharnx-0.1.0/pyharnx/llm/fake.py +240 -0
- pyharnx-0.1.0/pyharnx/llm/provider.py +81 -0
- pyharnx-0.1.0/pyharnx/llm/providers/__init__.py +130 -0
- pyharnx-0.1.0/pyharnx/llm/providers/_http.py +361 -0
- pyharnx-0.1.0/pyharnx/llm/providers/_single.py +221 -0
- pyharnx-0.1.0/pyharnx/llm/providers/_trace.py +48 -0
- pyharnx-0.1.0/pyharnx/llm/providers/anthropic.py +585 -0
- pyharnx-0.1.0/pyharnx/llm/providers/chat_completions.py +644 -0
- pyharnx-0.1.0/pyharnx/llm/providers/responses.py +705 -0
- pyharnx-0.1.0/pyharnx/llm/registry.py +72 -0
- pyharnx-0.1.0/pyharnx/llm/serde.py +92 -0
- pyharnx-0.1.0/pyharnx/llm/types.py +171 -0
- pyharnx-0.1.0/pyharnx/logs.py +109 -0
- pyharnx-0.1.0/pyharnx/prompts/__init__.py +24 -0
- pyharnx-0.1.0/pyharnx/prompts/environment.py +68 -0
- pyharnx-0.1.0/pyharnx/prompts/project.py +78 -0
- pyharnx-0.1.0/pyharnx/prompts/prompts.toml +116 -0
- pyharnx-0.1.0/pyharnx/prompts/system.py +137 -0
- pyharnx-0.1.0/pyharnx/session/__init__.py +53 -0
- pyharnx-0.1.0/pyharnx/session/recorder.py +160 -0
- pyharnx-0.1.0/pyharnx/session/resume.py +139 -0
- pyharnx-0.1.0/pyharnx/session/store.py +102 -0
- pyharnx-0.1.0/pyharnx/session/transcript.py +416 -0
- pyharnx-0.1.0/pyharnx/tools/__init__.py +43 -0
- pyharnx-0.1.0/pyharnx/tools/base.py +155 -0
- pyharnx-0.1.0/pyharnx/tools/fs.py +309 -0
- pyharnx-0.1.0/pyharnx/tools/html_text.py +179 -0
- pyharnx-0.1.0/pyharnx/tools/registry.py +53 -0
- pyharnx-0.1.0/pyharnx/tools/search.py +270 -0
- pyharnx-0.1.0/pyharnx/tools/shell.py +264 -0
- pyharnx-0.1.0/pyharnx/tools/skills.py +254 -0
- pyharnx-0.1.0/pyharnx/tools/web.py +394 -0
- pyharnx-0.1.0/pyproject.toml +95 -0
- pyharnx-0.1.0/pyproject.toml.orig +69 -0
pyharnx-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Liyan Xu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pyharnx-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pyharnx
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A minimal agent harness in Python, built for experiments — a lightweight alternative to pi
|
|
5
|
+
Keywords: agents,llm,agent harness,experiments,research,reproducibility
|
|
6
|
+
Author: Liyan Xu
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
17
|
+
Requires-Dist: anthropic>=0.40
|
|
18
|
+
Requires-Dist: httpx>=0.27
|
|
19
|
+
Requires-Dist: markdown-it-py>=3.0
|
|
20
|
+
Requires-Dist: prompt-toolkit>=3.0
|
|
21
|
+
Requires-Dist: pydantic>=2.9
|
|
22
|
+
Requires-Dist: pyyaml>=6.0.3
|
|
23
|
+
Requires-Dist: rich>=13.0
|
|
24
|
+
Requires-Dist: ddgs>=9.16.0 ; extra == 'ddgs'
|
|
25
|
+
Requires-Python: >=3.12
|
|
26
|
+
Project-URL: Repository, https://github.com/lxucs/pyharnx
|
|
27
|
+
Project-URL: Documentation, https://github.com/lxucs/pyharnx/tree/main/docs
|
|
28
|
+
Project-URL: Issues, https://github.com/lxucs/pyharnx/issues
|
|
29
|
+
Provides-Extra: ddgs
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# pyharnx
|
|
33
|
+
|
|
34
|
+
[](https://github.com/lxucs/pyharnx/actions/workflows/ci.yml)
|
|
35
|
+
[](https://github.com/lxucs/pyharnx/blob/main/pyproject.toml)
|
|
36
|
+
[](https://github.com/lxucs/pyharnx/blob/main/LICENSE)
|
|
37
|
+
|
|
38
|
+
pyharnx is **a minimal agent harness built for experiments, and a lightweight
|
|
39
|
+
Python alternative to [pi](https://github.com/earendil-works/pi)**, short for
|
|
40
|
+
**Py**thon **harn**ess for e**x**periments. Small enough to read in an
|
|
41
|
+
afternoon, complete enough to run them end to end.
|
|
42
|
+
|
|
43
|
+
It keeps pi's layering — `llm/` for pi-ai, `agent/` for pi-agent-core, a pure
|
|
44
|
+
loop wrapped by a stateful `Agent` — in Python, so the harness runs locally in
|
|
45
|
+
the same process as the rest of an experiment: the data, the evaluation, the
|
|
46
|
+
analysis. Where it departs from pi, and why:
|
|
47
|
+
[architecture.md](https://github.com/lxucs/pyharnx/blob/main/docs/architecture.md#relationship-to-pi).
|
|
48
|
+
|
|
49
|
+
At its core is a local agentic loop: the model reads and writes files, runs
|
|
50
|
+
commands and searches the web, with whichever of those tools you give it. On
|
|
51
|
+
top of it:
|
|
52
|
+
|
|
53
|
+
- **An interactive terminal**, to work with the agent directly — thinking and
|
|
54
|
+
tool calls as they stream, a token, cache and cost readout, and sessions that
|
|
55
|
+
resume and export as a web page.
|
|
56
|
+
- **A Python API**, to build on it — `from pyharnx.agent import Agent` is
|
|
57
|
+
the whole integration. [`search_agent/`](https://github.com/lxucs/pyharnx/tree/main/search_agent) is a complete search
|
|
58
|
+
agent built that way.
|
|
59
|
+
|
|
60
|
+
<sub>Note: pyharnx was previously named lab-harness; the demo and report below
|
|
61
|
+
show the old name.</sub>
|
|
62
|
+
|
|
63
|
+
A run in the terminal:
|
|
64
|
+
|
|
65
|
+
<img src="https://github.com/lxucs/pyharnx/raw/main/img/demo.gif" width="600" alt="pyharnx in the terminal: a question answered from a handful of documents, one tool call at a time">
|
|
66
|
+
|
|
67
|
+
The [trajectory report](https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html) a run records by `/export` in the terminal — the whole agentic trace for easy reading:
|
|
68
|
+
|
|
69
|
+
<a href="https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html"><img src="https://github.com/lxucs/pyharnx/raw/main/img/report.png" width="600" alt="The trajectory report of a search agent run: turns, requests, tool calls, tokens, cache and cost, then every step"></a>
|
|
70
|
+
|
|
71
|
+
## Features
|
|
72
|
+
|
|
73
|
+
An agent experiment needs what a product harness rarely gives: the exact request
|
|
74
|
+
behind every response, and the freedom to swap one piece — a tool, a hook, a
|
|
75
|
+
provider — without forking the rest. pyharnx keeps the core small enough to
|
|
76
|
+
hold in your head, with the seams where those changes go.
|
|
77
|
+
|
|
78
|
+
- **Minimal.** The stateless agent loop is about 500 lines of code, in
|
|
79
|
+
[`agent/loop.py`](https://github.com/lxucs/pyharnx/blob/main/pyharnx/agent/loop.py); the stateful `Agent` that wraps
|
|
80
|
+
it — transcript, subscribers, abort — about 150, in
|
|
81
|
+
[`agent/agent.py`](https://github.com/lxucs/pyharnx/blob/main/pyharnx/agent/agent.py). No other framework dependencies.
|
|
82
|
+
- **An agent in a few lines.** `route` a provider, pick tools, build an
|
|
83
|
+
`Agent`, `await agent.prompt(...)`. The run records itself as it goes, so the
|
|
84
|
+
transcript, the [HTML report](https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html) and the token
|
|
85
|
+
and cost numbers come with it.
|
|
86
|
+
- **Every request reproducible.** A session records the system prompt, tools,
|
|
87
|
+
model, reasoning effort and config each request was sent with.
|
|
88
|
+
[`trajectories.py --wire`](https://github.com/lxucs/pyharnx/blob/main/examples/trajectories.py) exports them as the JSON
|
|
89
|
+
bodies the endpoint got. See [trajectories](https://github.com/lxucs/pyharnx/blob/main/docs/sessions.md#trajectories).
|
|
90
|
+
- **One loop, many models.** Claude, OpenAI, DeepSeek, GLM, or any other
|
|
91
|
+
OpenAI-compatible endpoint. Every endpoint and model is a table in
|
|
92
|
+
[`llm/catalog.toml`](https://github.com/lxucs/pyharnx/blob/main/pyharnx/llm/catalog.toml), so a new vendor or model
|
|
93
|
+
is a few lines of TOML, not code.
|
|
94
|
+
|
|
95
|
+
## Architecture
|
|
96
|
+
|
|
97
|
+
Three layers. Dependencies point strictly downward: each box imports only from
|
|
98
|
+
the boxes below it, and `llm/` from no other layer. (Every layer reads the leaf
|
|
99
|
+
modules `config.py` and `logs.py`, which import only each other.)
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
cli/ terminal, json sink (subscribers)
|
|
103
|
+
│
|
|
104
|
+
▼
|
|
105
|
+
session/ transcripts (a subscriber too)
|
|
106
|
+
│
|
|
107
|
+
▼
|
|
108
|
+
agent/ prompts/ the loop · the system prompt
|
|
109
|
+
│
|
|
110
|
+
▼
|
|
111
|
+
tools/ built-ins, the registry
|
|
112
|
+
│
|
|
113
|
+
▼
|
|
114
|
+
llm/ providers, messages, streaming
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
| Layer | Responsibility |
|
|
118
|
+
|---|---|
|
|
119
|
+
| `llm/` | Provider-neutral LLM access — messages, models, streaming, tool declarations |
|
|
120
|
+
| `agent/` | The agentic loop and a stateful `Agent` that owns the transcript and emits events |
|
|
121
|
+
| `tools/` | Built-in capabilities and the registry that declares them to the model |
|
|
122
|
+
| `session/` | Append-only JSONL transcripts, resume, rebuilding requests — a subscriber, not a dependency |
|
|
123
|
+
| `prompts/` | The system prompt: the configured sections, the environment, the project's `AGENTS.md` — built once and handed to the agent as a string |
|
|
124
|
+
| `cli/` | Terminal and JSONL subscribers to the event stream |
|
|
125
|
+
|
|
126
|
+
Two seams carry almost everything extensible:
|
|
127
|
+
|
|
128
|
+
**The event stream.** `Agent.subscribe(listener)` is the only way to observe a
|
|
129
|
+
run. The terminal is a subscriber; so is the JSONL writer. Every event is a
|
|
130
|
+
frozen dataclass of JSON primitives, enforced by a round-trip test — which is
|
|
131
|
+
what lets a frontend in another language be a third subscriber later.
|
|
132
|
+
|
|
133
|
+
**The hooks.** `before_tool_call`, `after_tool_call`, `prepare_request`, and
|
|
134
|
+
`finish_turn`. A feature that fits a hook does not belong in the loop — tool
|
|
135
|
+
approval is one, which is why `-p` and interactive modes differ without the
|
|
136
|
+
loop branching. Context compaction will be another.
|
|
137
|
+
|
|
138
|
+
Details in [docs/architecture.md](https://github.com/lxucs/pyharnx/blob/main/docs/architecture.md).
|
|
139
|
+
|
|
140
|
+
## Install
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
uv tool install pyharnx # the pyharnx command, on your PATH
|
|
144
|
+
pip install pyharnx # or into the current environment
|
|
145
|
+
uv add pyharnx # or as a dependency of your project
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`pyharnx[ddgs]` adds the keyless web search backend. To read and change the
|
|
149
|
+
code as you go, work from a clone instead: `uv sync`, then `uv run pyharnx`.
|
|
150
|
+
|
|
151
|
+
## Quick start
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
export OPENAI_API_KEY=sk-... # or api_key in .pyharnx/config.local.toml
|
|
155
|
+
export TAVILY_API_KEY=tvly-... # optional, for web_search
|
|
156
|
+
pyharnx # interactive terminal
|
|
157
|
+
pyharnx -p "summarize the config module" # one-shot
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Check [examples/terminal.md](https://github.com/lxucs/pyharnx/blob/main/examples/terminal.md) for more details on the interactive terminal.
|
|
161
|
+
|
|
162
|
+
To keep settings without exporting them each time, put them in
|
|
163
|
+
`~/.pyharnx/config.local.toml` for every project. It merges over the
|
|
164
|
+
defaults, so it holds only the keys you change:
|
|
165
|
+
|
|
166
|
+
```toml
|
|
167
|
+
[agent]
|
|
168
|
+
model = "gpt-6.1-sol" # the default model; --model still wins
|
|
169
|
+
|
|
170
|
+
[providers.openai.openai]
|
|
171
|
+
api_key = "sk-..." # OPENAI_API_KEY still wins if set
|
|
172
|
+
|
|
173
|
+
[tools.web.tavily]
|
|
174
|
+
api_key = "tvly-..."
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Every key, and the order the layers apply in:
|
|
178
|
+
[docs/configuration.md](https://github.com/lxucs/pyharnx/blob/main/docs/configuration.md).
|
|
179
|
+
|
|
180
|
+
## From Python
|
|
181
|
+
|
|
182
|
+
The CLI is a thin layer over a library, so an experiment can drive the agent
|
|
183
|
+
directly:
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
import asyncio
|
|
187
|
+
|
|
188
|
+
from pyharnx.agent import Agent
|
|
189
|
+
from pyharnx.config import load_config
|
|
190
|
+
from pyharnx.llm.providers import route
|
|
191
|
+
from pyharnx.tools import default_registry
|
|
192
|
+
|
|
193
|
+
config = load_config()
|
|
194
|
+
model, provider = route(None, config) # $PYHARNX_MODEL, else agent.model
|
|
195
|
+
tools = default_registry().select(["read", "ls", "grep", "glob"])
|
|
196
|
+
agent = Agent(model=model, provider=provider, tools=tools, config=config)
|
|
197
|
+
messages = asyncio.run(agent.prompt("What does this project do?"))
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
That agent has no system prompt. `build_system_prompt` from `pyharnx.prompts`
|
|
201
|
+
builds the one the CLI sends, as [quickstart.py](https://github.com/lxucs/pyharnx/blob/main/examples/quickstart.py) shows;
|
|
202
|
+
see the `[prompts]` sections in [prompts.toml](https://github.com/lxucs/pyharnx/blob/main/pyharnx/prompts/prompts.toml).
|
|
203
|
+
|
|
204
|
+
[examples/](https://github.com/lxucs/pyharnx/tree/main/examples) goes further: streaming events, a custom tool, all four
|
|
205
|
+
hooks, a scripted model that needs no key, and exporting a session's requests
|
|
206
|
+
for training. Configuration and every environment variable:
|
|
207
|
+
[docs/configuration.md](https://github.com/lxucs/pyharnx/blob/main/docs/configuration.md).
|
|
208
|
+
|
|
209
|
+
## Example: a search agent built on pyharnx
|
|
210
|
+
|
|
211
|
+
[`search_agent/`](https://github.com/lxucs/pyharnx/tree/main/search_agent) is a search agent — an agent that answers a
|
|
212
|
+
question by searching and reading documents — running as a program you can start
|
|
213
|
+
with one command. The agent itself is a few lines:
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
model, provider = route(None, config) # the model, from config alone
|
|
217
|
+
tools = tools_for(settings.tools, settings.corpus) # built-ins plus search_docs
|
|
218
|
+
agent = Agent(
|
|
219
|
+
model=model,
|
|
220
|
+
provider=provider,
|
|
221
|
+
tools=tools,
|
|
222
|
+
config=config,
|
|
223
|
+
system_prompt=SYSTEM_PROMPT.format(corpus=settings.corpus),
|
|
224
|
+
cwd=str(settings.cwd),
|
|
225
|
+
)
|
|
226
|
+
messages = await agent.prompt(question)
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
`uv run python -m search_agent` runs it, and a real run is committed to look
|
|
230
|
+
at: [the report it produced](https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html), with the
|
|
231
|
+
trajectory as JSON beside it.
|
|
232
|
+
|
|
233
|
+
## Documentation
|
|
234
|
+
|
|
235
|
+
| Page | Covers |
|
|
236
|
+
|---|---|
|
|
237
|
+
| [examples/](https://github.com/lxucs/pyharnx/tree/main/examples) | Runnable usage, from the terminal and from Python |
|
|
238
|
+
| [search_agent/](https://github.com/lxucs/pyharnx/tree/main/search_agent) | A search agent: a whole program in Python, and a committed run to read |
|
|
239
|
+
| [architecture.md](https://github.com/lxucs/pyharnx/blob/main/docs/architecture.md) | Layering, module boundaries, deviations from pi |
|
|
240
|
+
| [events.md](https://github.com/lxucs/pyharnx/blob/main/docs/events.md) | The event protocol between runtime and frontend |
|
|
241
|
+
| [providers.md](https://github.com/lxucs/pyharnx/blob/main/docs/providers.md) | Provider contract, profiles, adding a vendor |
|
|
242
|
+
| [tools.md](https://github.com/lxucs/pyharnx/blob/main/docs/tools.md) | Tool contract, built-ins, adding a tool |
|
|
243
|
+
| [sessions.md](https://github.com/lxucs/pyharnx/blob/main/docs/sessions.md) | Transcript format, resume, rebuilding trajectories |
|
|
244
|
+
| [cli.md](https://github.com/lxucs/pyharnx/blob/main/docs/cli.md) | Terminal, flags, keybindings, the usage and cost readout |
|
|
245
|
+
| [configuration.md](https://github.com/lxucs/pyharnx/blob/main/docs/configuration.md) | Config files, environment variables, models and prices, prompts |
|
|
246
|
+
| [contributing.md](https://github.com/lxucs/pyharnx/blob/main/docs/contributing.md) | Code conventions, architectural invariants, config rules |
|
|
247
|
+
|
|
248
|
+
Contributing: [docs/contributing.md](https://github.com/lxucs/pyharnx/blob/main/docs/contributing.md). AI coding agents
|
|
249
|
+
should also read [AGENTS.md](https://github.com/lxucs/pyharnx/blob/main/AGENTS.md).
|
|
250
|
+
|
|
251
|
+
## Roadmap
|
|
252
|
+
|
|
253
|
+
- **Context compaction** — the one planned piece unbuilt. It fits the
|
|
254
|
+
`prepare_request` hook, so it lands without touching the loop.
|
|
255
|
+
- **Anthropic prompt caching** — the Messages adapter sends no `cache_control`
|
|
256
|
+
markers yet, so Anthropic's cache hit rate reads 0%.
|
|
257
|
+
|
|
258
|
+
Not planned: MCP, sub-agents, plan mode, an RPC control channel,
|
|
259
|
+
extensions-as-plugins, sandboxing, provider-native `web_search`. What each item
|
|
260
|
+
needs, and why those are left out: [docs/README.md](https://github.com/lxucs/pyharnx/blob/main/docs/README.md#todo).
|
|
261
|
+
|
|
262
|
+
## Citation
|
|
263
|
+
|
|
264
|
+
If pyharnx helps your research, GitHub's **Cite this repository** button
|
|
265
|
+
gives a citation in APA or BibTeX, from [CITATION.cff](https://github.com/lxucs/pyharnx/blob/main/CITATION.cff).
|
|
266
|
+
|
|
267
|
+
## License
|
|
268
|
+
|
|
269
|
+
[MIT](https://github.com/lxucs/pyharnx/blob/main/LICENSE).
|
pyharnx-0.1.0/README.md
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# pyharnx
|
|
2
|
+
|
|
3
|
+
[](https://github.com/lxucs/pyharnx/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/lxucs/pyharnx/blob/main/pyproject.toml)
|
|
5
|
+
[](https://github.com/lxucs/pyharnx/blob/main/LICENSE)
|
|
6
|
+
|
|
7
|
+
pyharnx is **a minimal agent harness built for experiments, and a lightweight
|
|
8
|
+
Python alternative to [pi](https://github.com/earendil-works/pi)**, short for
|
|
9
|
+
**Py**thon **harn**ess for e**x**periments. Small enough to read in an
|
|
10
|
+
afternoon, complete enough to run them end to end.
|
|
11
|
+
|
|
12
|
+
It keeps pi's layering — `llm/` for pi-ai, `agent/` for pi-agent-core, a pure
|
|
13
|
+
loop wrapped by a stateful `Agent` — in Python, so the harness runs locally in
|
|
14
|
+
the same process as the rest of an experiment: the data, the evaluation, the
|
|
15
|
+
analysis. Where it departs from pi, and why:
|
|
16
|
+
[architecture.md](https://github.com/lxucs/pyharnx/blob/main/docs/architecture.md#relationship-to-pi).
|
|
17
|
+
|
|
18
|
+
At its core is a local agentic loop: the model reads and writes files, runs
|
|
19
|
+
commands and searches the web, with whichever of those tools you give it. On
|
|
20
|
+
top of it:
|
|
21
|
+
|
|
22
|
+
- **An interactive terminal**, to work with the agent directly — thinking and
|
|
23
|
+
tool calls as they stream, a token, cache and cost readout, and sessions that
|
|
24
|
+
resume and export as a web page.
|
|
25
|
+
- **A Python API**, to build on it — `from pyharnx.agent import Agent` is
|
|
26
|
+
the whole integration. [`search_agent/`](https://github.com/lxucs/pyharnx/tree/main/search_agent) is a complete search
|
|
27
|
+
agent built that way.
|
|
28
|
+
|
|
29
|
+
<sub>Note: pyharnx was previously named lab-harness; the demo and report below
|
|
30
|
+
show the old name.</sub>
|
|
31
|
+
|
|
32
|
+
A run in the terminal:
|
|
33
|
+
|
|
34
|
+
<img src="https://github.com/lxucs/pyharnx/raw/main/img/demo.gif" width="600" alt="pyharnx in the terminal: a question answered from a handful of documents, one tool call at a time">
|
|
35
|
+
|
|
36
|
+
The [trajectory report](https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html) a run records by `/export` in the terminal — the whole agentic trace for easy reading:
|
|
37
|
+
|
|
38
|
+
<a href="https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html"><img src="https://github.com/lxucs/pyharnx/raw/main/img/report.png" width="600" alt="The trajectory report of a search agent run: turns, requests, tool calls, tokens, cache and cost, then every step"></a>
|
|
39
|
+
|
|
40
|
+
## Features
|
|
41
|
+
|
|
42
|
+
An agent experiment needs what a product harness rarely gives: the exact request
|
|
43
|
+
behind every response, and the freedom to swap one piece — a tool, a hook, a
|
|
44
|
+
provider — without forking the rest. pyharnx keeps the core small enough to
|
|
45
|
+
hold in your head, with the seams where those changes go.
|
|
46
|
+
|
|
47
|
+
- **Minimal.** The stateless agent loop is about 500 lines of code, in
|
|
48
|
+
[`agent/loop.py`](https://github.com/lxucs/pyharnx/blob/main/pyharnx/agent/loop.py); the stateful `Agent` that wraps
|
|
49
|
+
it — transcript, subscribers, abort — about 150, in
|
|
50
|
+
[`agent/agent.py`](https://github.com/lxucs/pyharnx/blob/main/pyharnx/agent/agent.py). No other framework dependencies.
|
|
51
|
+
- **An agent in a few lines.** `route` a provider, pick tools, build an
|
|
52
|
+
`Agent`, `await agent.prompt(...)`. The run records itself as it goes, so the
|
|
53
|
+
transcript, the [HTML report](https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html) and the token
|
|
54
|
+
and cost numbers come with it.
|
|
55
|
+
- **Every request reproducible.** A session records the system prompt, tools,
|
|
56
|
+
model, reasoning effort and config each request was sent with.
|
|
57
|
+
[`trajectories.py --wire`](https://github.com/lxucs/pyharnx/blob/main/examples/trajectories.py) exports them as the JSON
|
|
58
|
+
bodies the endpoint got. See [trajectories](https://github.com/lxucs/pyharnx/blob/main/docs/sessions.md#trajectories).
|
|
59
|
+
- **One loop, many models.** Claude, OpenAI, DeepSeek, GLM, or any other
|
|
60
|
+
OpenAI-compatible endpoint. Every endpoint and model is a table in
|
|
61
|
+
[`llm/catalog.toml`](https://github.com/lxucs/pyharnx/blob/main/pyharnx/llm/catalog.toml), so a new vendor or model
|
|
62
|
+
is a few lines of TOML, not code.
|
|
63
|
+
|
|
64
|
+
## Architecture
|
|
65
|
+
|
|
66
|
+
Three layers. Dependencies point strictly downward: each box imports only from
|
|
67
|
+
the boxes below it, and `llm/` from no other layer. (Every layer reads the leaf
|
|
68
|
+
modules `config.py` and `logs.py`, which import only each other.)
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
cli/ terminal, json sink (subscribers)
|
|
72
|
+
│
|
|
73
|
+
▼
|
|
74
|
+
session/ transcripts (a subscriber too)
|
|
75
|
+
│
|
|
76
|
+
▼
|
|
77
|
+
agent/ prompts/ the loop · the system prompt
|
|
78
|
+
│
|
|
79
|
+
▼
|
|
80
|
+
tools/ built-ins, the registry
|
|
81
|
+
│
|
|
82
|
+
▼
|
|
83
|
+
llm/ providers, messages, streaming
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
| Layer | Responsibility |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `llm/` | Provider-neutral LLM access — messages, models, streaming, tool declarations |
|
|
89
|
+
| `agent/` | The agentic loop and a stateful `Agent` that owns the transcript and emits events |
|
|
90
|
+
| `tools/` | Built-in capabilities and the registry that declares them to the model |
|
|
91
|
+
| `session/` | Append-only JSONL transcripts, resume, rebuilding requests — a subscriber, not a dependency |
|
|
92
|
+
| `prompts/` | The system prompt: the configured sections, the environment, the project's `AGENTS.md` — built once and handed to the agent as a string |
|
|
93
|
+
| `cli/` | Terminal and JSONL subscribers to the event stream |
|
|
94
|
+
|
|
95
|
+
Two seams carry almost everything extensible:
|
|
96
|
+
|
|
97
|
+
**The event stream.** `Agent.subscribe(listener)` is the only way to observe a
|
|
98
|
+
run. The terminal is a subscriber; so is the JSONL writer. Every event is a
|
|
99
|
+
frozen dataclass of JSON primitives, enforced by a round-trip test — which is
|
|
100
|
+
what lets a frontend in another language be a third subscriber later.
|
|
101
|
+
|
|
102
|
+
**The hooks.** `before_tool_call`, `after_tool_call`, `prepare_request`, and
|
|
103
|
+
`finish_turn`. A feature that fits a hook does not belong in the loop — tool
|
|
104
|
+
approval is one, which is why `-p` and interactive modes differ without the
|
|
105
|
+
loop branching. Context compaction will be another.
|
|
106
|
+
|
|
107
|
+
Details in [docs/architecture.md](https://github.com/lxucs/pyharnx/blob/main/docs/architecture.md).
|
|
108
|
+
|
|
109
|
+
## Install
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
uv tool install pyharnx # the pyharnx command, on your PATH
|
|
113
|
+
pip install pyharnx # or into the current environment
|
|
114
|
+
uv add pyharnx # or as a dependency of your project
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`pyharnx[ddgs]` adds the keyless web search backend. To read and change the
|
|
118
|
+
code as you go, work from a clone instead: `uv sync`, then `uv run pyharnx`.
|
|
119
|
+
|
|
120
|
+
## Quick start
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
export OPENAI_API_KEY=sk-... # or api_key in .pyharnx/config.local.toml
|
|
124
|
+
export TAVILY_API_KEY=tvly-... # optional, for web_search
|
|
125
|
+
pyharnx # interactive terminal
|
|
126
|
+
pyharnx -p "summarize the config module" # one-shot
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Check [examples/terminal.md](https://github.com/lxucs/pyharnx/blob/main/examples/terminal.md) for more details on the interactive terminal.
|
|
130
|
+
|
|
131
|
+
To keep settings without exporting them each time, put them in
|
|
132
|
+
`~/.pyharnx/config.local.toml` for every project. It merges over the
|
|
133
|
+
defaults, so it holds only the keys you change:
|
|
134
|
+
|
|
135
|
+
```toml
|
|
136
|
+
[agent]
|
|
137
|
+
model = "gpt-6.1-sol" # the default model; --model still wins
|
|
138
|
+
|
|
139
|
+
[providers.openai.openai]
|
|
140
|
+
api_key = "sk-..." # OPENAI_API_KEY still wins if set
|
|
141
|
+
|
|
142
|
+
[tools.web.tavily]
|
|
143
|
+
api_key = "tvly-..."
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Every key, and the order the layers apply in:
|
|
147
|
+
[docs/configuration.md](https://github.com/lxucs/pyharnx/blob/main/docs/configuration.md).
|
|
148
|
+
|
|
149
|
+
## From Python
|
|
150
|
+
|
|
151
|
+
The CLI is a thin layer over a library, so an experiment can drive the agent
|
|
152
|
+
directly:
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
import asyncio
|
|
156
|
+
|
|
157
|
+
from pyharnx.agent import Agent
|
|
158
|
+
from pyharnx.config import load_config
|
|
159
|
+
from pyharnx.llm.providers import route
|
|
160
|
+
from pyharnx.tools import default_registry
|
|
161
|
+
|
|
162
|
+
config = load_config()
|
|
163
|
+
model, provider = route(None, config) # $PYHARNX_MODEL, else agent.model
|
|
164
|
+
tools = default_registry().select(["read", "ls", "grep", "glob"])
|
|
165
|
+
agent = Agent(model=model, provider=provider, tools=tools, config=config)
|
|
166
|
+
messages = asyncio.run(agent.prompt("What does this project do?"))
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
That agent has no system prompt. `build_system_prompt` from `pyharnx.prompts`
|
|
170
|
+
builds the one the CLI sends, as [quickstart.py](https://github.com/lxucs/pyharnx/blob/main/examples/quickstart.py) shows;
|
|
171
|
+
see the `[prompts]` sections in [prompts.toml](https://github.com/lxucs/pyharnx/blob/main/pyharnx/prompts/prompts.toml).
|
|
172
|
+
|
|
173
|
+
[examples/](https://github.com/lxucs/pyharnx/tree/main/examples) goes further: streaming events, a custom tool, all four
|
|
174
|
+
hooks, a scripted model that needs no key, and exporting a session's requests
|
|
175
|
+
for training. Configuration and every environment variable:
|
|
176
|
+
[docs/configuration.md](https://github.com/lxucs/pyharnx/blob/main/docs/configuration.md).
|
|
177
|
+
|
|
178
|
+
## Example: a search agent built on pyharnx
|
|
179
|
+
|
|
180
|
+
[`search_agent/`](https://github.com/lxucs/pyharnx/tree/main/search_agent) is a search agent — an agent that answers a
|
|
181
|
+
question by searching and reading documents — running as a program you can start
|
|
182
|
+
with one command. The agent itself is a few lines:
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
model, provider = route(None, config) # the model, from config alone
|
|
186
|
+
tools = tools_for(settings.tools, settings.corpus) # built-ins plus search_docs
|
|
187
|
+
agent = Agent(
|
|
188
|
+
model=model,
|
|
189
|
+
provider=provider,
|
|
190
|
+
tools=tools,
|
|
191
|
+
config=config,
|
|
192
|
+
system_prompt=SYSTEM_PROMPT.format(corpus=settings.corpus),
|
|
193
|
+
cwd=str(settings.cwd),
|
|
194
|
+
)
|
|
195
|
+
messages = await agent.prompt(question)
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`uv run python -m search_agent` runs it, and a real run is committed to look
|
|
199
|
+
at: [the report it produced](https://lxucs.github.io/pyharnx/search_agent/runs/793/report.html), with the
|
|
200
|
+
trajectory as JSON beside it.
|
|
201
|
+
|
|
202
|
+
## Documentation
|
|
203
|
+
|
|
204
|
+
| Page | Covers |
|
|
205
|
+
|---|---|
|
|
206
|
+
| [examples/](https://github.com/lxucs/pyharnx/tree/main/examples) | Runnable usage, from the terminal and from Python |
|
|
207
|
+
| [search_agent/](https://github.com/lxucs/pyharnx/tree/main/search_agent) | A search agent: a whole program in Python, and a committed run to read |
|
|
208
|
+
| [architecture.md](https://github.com/lxucs/pyharnx/blob/main/docs/architecture.md) | Layering, module boundaries, deviations from pi |
|
|
209
|
+
| [events.md](https://github.com/lxucs/pyharnx/blob/main/docs/events.md) | The event protocol between runtime and frontend |
|
|
210
|
+
| [providers.md](https://github.com/lxucs/pyharnx/blob/main/docs/providers.md) | Provider contract, profiles, adding a vendor |
|
|
211
|
+
| [tools.md](https://github.com/lxucs/pyharnx/blob/main/docs/tools.md) | Tool contract, built-ins, adding a tool |
|
|
212
|
+
| [sessions.md](https://github.com/lxucs/pyharnx/blob/main/docs/sessions.md) | Transcript format, resume, rebuilding trajectories |
|
|
213
|
+
| [cli.md](https://github.com/lxucs/pyharnx/blob/main/docs/cli.md) | Terminal, flags, keybindings, the usage and cost readout |
|
|
214
|
+
| [configuration.md](https://github.com/lxucs/pyharnx/blob/main/docs/configuration.md) | Config files, environment variables, models and prices, prompts |
|
|
215
|
+
| [contributing.md](https://github.com/lxucs/pyharnx/blob/main/docs/contributing.md) | Code conventions, architectural invariants, config rules |
|
|
216
|
+
|
|
217
|
+
Contributing: [docs/contributing.md](https://github.com/lxucs/pyharnx/blob/main/docs/contributing.md). AI coding agents
|
|
218
|
+
should also read [AGENTS.md](https://github.com/lxucs/pyharnx/blob/main/AGENTS.md).
|
|
219
|
+
|
|
220
|
+
## Roadmap
|
|
221
|
+
|
|
222
|
+
- **Context compaction** — the one planned piece unbuilt. It fits the
|
|
223
|
+
`prepare_request` hook, so it lands without touching the loop.
|
|
224
|
+
- **Anthropic prompt caching** — the Messages adapter sends no `cache_control`
|
|
225
|
+
markers yet, so Anthropic's cache hit rate reads 0%.
|
|
226
|
+
|
|
227
|
+
Not planned: MCP, sub-agents, plan mode, an RPC control channel,
|
|
228
|
+
extensions-as-plugins, sandboxing, provider-native `web_search`. What each item
|
|
229
|
+
needs, and why those are left out: [docs/README.md](https://github.com/lxucs/pyharnx/blob/main/docs/README.md#todo).
|
|
230
|
+
|
|
231
|
+
## Citation
|
|
232
|
+
|
|
233
|
+
If pyharnx helps your research, GitHub's **Cite this repository** button
|
|
234
|
+
gives a citation in APA or BibTeX, from [CITATION.cff](https://github.com/lxucs/pyharnx/blob/main/CITATION.cff).
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
[MIT](https://github.com/lxucs/pyharnx/blob/main/LICENSE).
|
|
File without changes
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""The agent runtime: a pure loop and a stateful wrapper around it."""
|
|
2
|
+
|
|
3
|
+
from pyharnx.agent.agent import Agent, AgentState
|
|
4
|
+
from pyharnx.agent.loop import run_agent_loop
|
|
5
|
+
from pyharnx.agent.types import (
|
|
6
|
+
AgentContext,
|
|
7
|
+
AgentEvent,
|
|
8
|
+
AgentTool,
|
|
9
|
+
LoopConfig,
|
|
10
|
+
ToolContext,
|
|
11
|
+
ToolResult,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
"Agent",
|
|
16
|
+
"AgentContext",
|
|
17
|
+
"AgentEvent",
|
|
18
|
+
"AgentState",
|
|
19
|
+
"AgentTool",
|
|
20
|
+
"LoopConfig",
|
|
21
|
+
"ToolContext",
|
|
22
|
+
"ToolResult",
|
|
23
|
+
"run_agent_loop",
|
|
24
|
+
]
|