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.
Files changed (56) hide show
  1. pyharnx-0.1.0/LICENSE +21 -0
  2. pyharnx-0.1.0/PKG-INFO +269 -0
  3. pyharnx-0.1.0/README.md +238 -0
  4. pyharnx-0.1.0/pyharnx/__init__.py +0 -0
  5. pyharnx-0.1.0/pyharnx/agent/__init__.py +24 -0
  6. pyharnx-0.1.0/pyharnx/agent/agent.py +210 -0
  7. pyharnx-0.1.0/pyharnx/agent/loop.py +783 -0
  8. pyharnx-0.1.0/pyharnx/agent/types.py +275 -0
  9. pyharnx-0.1.0/pyharnx/cli/__init__.py +5 -0
  10. pyharnx-0.1.0/pyharnx/cli/approval.py +119 -0
  11. pyharnx-0.1.0/pyharnx/cli/commands.py +312 -0
  12. pyharnx-0.1.0/pyharnx/cli/export.html +777 -0
  13. pyharnx-0.1.0/pyharnx/cli/export.py +634 -0
  14. pyharnx-0.1.0/pyharnx/cli/json_sink.py +31 -0
  15. pyharnx-0.1.0/pyharnx/cli/main.py +545 -0
  16. pyharnx-0.1.0/pyharnx/cli/renderers.py +734 -0
  17. pyharnx-0.1.0/pyharnx/cli/terminal.py +860 -0
  18. pyharnx-0.1.0/pyharnx/cli/usage.py +203 -0
  19. pyharnx-0.1.0/pyharnx/config.py +1050 -0
  20. pyharnx-0.1.0/pyharnx/llm/__init__.py +34 -0
  21. pyharnx-0.1.0/pyharnx/llm/catalog.toml +373 -0
  22. pyharnx-0.1.0/pyharnx/llm/events.py +107 -0
  23. pyharnx-0.1.0/pyharnx/llm/fake.py +240 -0
  24. pyharnx-0.1.0/pyharnx/llm/provider.py +81 -0
  25. pyharnx-0.1.0/pyharnx/llm/providers/__init__.py +130 -0
  26. pyharnx-0.1.0/pyharnx/llm/providers/_http.py +361 -0
  27. pyharnx-0.1.0/pyharnx/llm/providers/_single.py +221 -0
  28. pyharnx-0.1.0/pyharnx/llm/providers/_trace.py +48 -0
  29. pyharnx-0.1.0/pyharnx/llm/providers/anthropic.py +585 -0
  30. pyharnx-0.1.0/pyharnx/llm/providers/chat_completions.py +644 -0
  31. pyharnx-0.1.0/pyharnx/llm/providers/responses.py +705 -0
  32. pyharnx-0.1.0/pyharnx/llm/registry.py +72 -0
  33. pyharnx-0.1.0/pyharnx/llm/serde.py +92 -0
  34. pyharnx-0.1.0/pyharnx/llm/types.py +171 -0
  35. pyharnx-0.1.0/pyharnx/logs.py +109 -0
  36. pyharnx-0.1.0/pyharnx/prompts/__init__.py +24 -0
  37. pyharnx-0.1.0/pyharnx/prompts/environment.py +68 -0
  38. pyharnx-0.1.0/pyharnx/prompts/project.py +78 -0
  39. pyharnx-0.1.0/pyharnx/prompts/prompts.toml +116 -0
  40. pyharnx-0.1.0/pyharnx/prompts/system.py +137 -0
  41. pyharnx-0.1.0/pyharnx/session/__init__.py +53 -0
  42. pyharnx-0.1.0/pyharnx/session/recorder.py +160 -0
  43. pyharnx-0.1.0/pyharnx/session/resume.py +139 -0
  44. pyharnx-0.1.0/pyharnx/session/store.py +102 -0
  45. pyharnx-0.1.0/pyharnx/session/transcript.py +416 -0
  46. pyharnx-0.1.0/pyharnx/tools/__init__.py +43 -0
  47. pyharnx-0.1.0/pyharnx/tools/base.py +155 -0
  48. pyharnx-0.1.0/pyharnx/tools/fs.py +309 -0
  49. pyharnx-0.1.0/pyharnx/tools/html_text.py +179 -0
  50. pyharnx-0.1.0/pyharnx/tools/registry.py +53 -0
  51. pyharnx-0.1.0/pyharnx/tools/search.py +270 -0
  52. pyharnx-0.1.0/pyharnx/tools/shell.py +264 -0
  53. pyharnx-0.1.0/pyharnx/tools/skills.py +254 -0
  54. pyharnx-0.1.0/pyharnx/tools/web.py +394 -0
  55. pyharnx-0.1.0/pyproject.toml +95 -0
  56. 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
+ [![CI](https://github.com/lxucs/pyharnx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lxucs/pyharnx/actions/workflows/ci.yml)
35
+ [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://github.com/lxucs/pyharnx/blob/main/pyproject.toml)
36
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](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).
@@ -0,0 +1,238 @@
1
+ # pyharnx
2
+
3
+ [![CI](https://github.com/lxucs/pyharnx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lxucs/pyharnx/actions/workflows/ci.yml)
4
+ [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://github.com/lxucs/pyharnx/blob/main/pyproject.toml)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](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
+ ]