thearc 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.
- thearc-0.1.0/PKG-INFO +173 -0
- thearc-0.1.0/README.md +149 -0
- thearc-0.1.0/pyproject.toml +51 -0
- thearc-0.1.0/setup.cfg +4 -0
- thearc-0.1.0/tests/test_ace.py +145 -0
- thearc-0.1.0/tests/test_ace_evaluation.py +45 -0
- thearc-0.1.0/tests/test_ace_toy.py +185 -0
- thearc-0.1.0/tests/test_agent_class.py +289 -0
- thearc-0.1.0/tests/test_agent_reflectors.py +240 -0
- thearc-0.1.0/tests/test_agents.py +39 -0
- thearc-0.1.0/tests/test_cli.py +48 -0
- thearc-0.1.0/tests/test_codex_reflector.py +510 -0
- thearc-0.1.0/tests/test_config.py +49 -0
- thearc-0.1.0/tests/test_cookbook.py +242 -0
- thearc-0.1.0/tests/test_cookbook_ace_flow.py +136 -0
- thearc-0.1.0/tests/test_curation_assessments.py +174 -0
- thearc-0.1.0/tests/test_curation_backends.py +167 -0
- thearc-0.1.0/tests/test_curation_flow.py +195 -0
- thearc-0.1.0/tests/test_curation_targets.py +106 -0
- thearc-0.1.0/tests/test_documentation.py +67 -0
- thearc-0.1.0/tests/test_evidence.py +301 -0
- thearc-0.1.0/tests/test_graphify_installation.py +115 -0
- thearc-0.1.0/tests/test_history.py +479 -0
- thearc-0.1.0/tests/test_history_exports.py +45 -0
- thearc-0.1.0/tests/test_learning_layout.py +90 -0
- thearc-0.1.0/tests/test_metaagent_diff.py +112 -0
- thearc-0.1.0/tests/test_metaagent_identity.py +194 -0
- thearc-0.1.0/tests/test_metaagent_workspace.py +109 -0
- thearc-0.1.0/tests/test_models.py +105 -0
- thearc-0.1.0/tests/test_package_support.py +25 -0
- thearc-0.1.0/tests/test_prompt_collection.py +193 -0
- thearc-0.1.0/tests/test_ranks.py +118 -0
- thearc-0.1.0/tests/test_reflection_cli.py +105 -0
- thearc-0.1.0/tests/test_reflections_flow.py +145 -0
- thearc-0.1.0/tests/test_reflector.py +141 -0
- thearc-0.1.0/tests/test_release_workflow.py +27 -0
- thearc-0.1.0/tests/test_scaling_selection.py +139 -0
- thearc-0.1.0/tests/test_session_date_filters.py +173 -0
- thearc-0.1.0/tests/test_session_search.py +77 -0
- thearc-0.1.0/tests/test_tracker.py +114 -0
- thearc-0.1.0/thearc/__init__.py +34 -0
- thearc-0.1.0/thearc/agents/__init__.py +26 -0
- thearc-0.1.0/thearc/agents/antigravity.py +8 -0
- thearc-0.1.0/thearc/agents/base.py +442 -0
- thearc-0.1.0/thearc/agents/claude.py +8 -0
- thearc-0.1.0/thearc/agents/codex.py +8 -0
- thearc-0.1.0/thearc/agents/pi.py +8 -0
- thearc-0.1.0/thearc/cli.py +23 -0
- thearc-0.1.0/thearc/config.py +173 -0
- thearc-0.1.0/thearc/flow/__init__.py +108 -0
- thearc-0.1.0/thearc/flow/decorators.py +380 -0
- thearc-0.1.0/thearc/flow/test.py +128 -0
- thearc-0.1.0/thearc/flow/utils.py +248 -0
- thearc-0.1.0/thearc/flow/viz.css +433 -0
- thearc-0.1.0/thearc/flow/viz.js +259 -0
- thearc-0.1.0/thearc/flow/viz.py +656 -0
- thearc-0.1.0/thearc/learning/__init__.py +145 -0
- thearc-0.1.0/thearc/learning/_compat.py +39 -0
- thearc-0.1.0/thearc/learning/ace/__init__.py +35 -0
- thearc-0.1.0/thearc/learning/ace/evaluation.py +70 -0
- thearc-0.1.0/thearc/learning/ace/pipeline.py +425 -0
- thearc-0.1.0/thearc/learning/ace/toy.py +262 -0
- thearc-0.1.0/thearc/learning/cli.py +25 -0
- thearc-0.1.0/thearc/learning/curation/__init__.py +22 -0
- thearc-0.1.0/thearc/learning/curation/assessments.py +182 -0
- thearc-0.1.0/thearc/learning/curation/cli.py +115 -0
- thearc-0.1.0/thearc/learning/curation/engine.py +182 -0
- thearc-0.1.0/thearc/learning/curation/epochs.py +121 -0
- thearc-0.1.0/thearc/learning/curation/factory.py +41 -0
- thearc-0.1.0/thearc/learning/curation/providers/__init__.py +10 -0
- thearc-0.1.0/thearc/learning/curation/providers/antigravity.py +16 -0
- thearc-0.1.0/thearc/learning/curation/providers/claude.py +15 -0
- thearc-0.1.0/thearc/learning/curation/providers/codex.py +21 -0
- thearc-0.1.0/thearc/learning/curation/structured.py +84 -0
- thearc-0.1.0/thearc/learning/curation/tools.py +210 -0
- thearc-0.1.0/thearc/learning/evidence/__init__.py +18 -0
- thearc-0.1.0/thearc/learning/evidence/cli.py +72 -0
- thearc-0.1.0/thearc/learning/evidence/exports.py +77 -0
- thearc-0.1.0/thearc/learning/evidence/snapshot.py +271 -0
- thearc-0.1.0/thearc/learning/evidence/tools.py +253 -0
- thearc-0.1.0/thearc/learning/privacy.py +61 -0
- thearc-0.1.0/thearc/learning/reflection/__init__.py +16 -0
- thearc-0.1.0/thearc/learning/reflection/backend.py +49 -0
- thearc-0.1.0/thearc/learning/reflection/cli.py +91 -0
- thearc-0.1.0/thearc/learning/reflection/engine.py +374 -0
- thearc-0.1.0/thearc/learning/reflection/factory.py +54 -0
- thearc-0.1.0/thearc/learning/reflection/flow.py +192 -0
- thearc-0.1.0/thearc/learning/reflection/providers/__init__.py +1 -0
- thearc-0.1.0/thearc/learning/reflection/providers/antigravity.py +127 -0
- thearc-0.1.0/thearc/learning/reflection/providers/claude.py +122 -0
- thearc-0.1.0/thearc/learning/reflection/providers/cli.py +65 -0
- thearc-0.1.0/thearc/learning/reflection/providers/codex.py +191 -0
- thearc-0.1.0/thearc/learning/runtime/__init__.py +9 -0
- thearc-0.1.0/thearc/learning/runtime/cli.py +42 -0
- thearc-0.1.0/thearc/learning/runtime/contracts.py +69 -0
- thearc-0.1.0/thearc/learning/runtime/handoff.py +152 -0
- thearc-0.1.0/thearc/learning/runtime/journal.py +148 -0
- thearc-0.1.0/thearc/learning/sessions/__init__.py +22 -0
- thearc-0.1.0/thearc/learning/sessions/adapters.py +473 -0
- thearc-0.1.0/thearc/learning/sessions/cli.py +107 -0
- thearc-0.1.0/thearc/learning/sessions/columnar.py +107 -0
- thearc-0.1.0/thearc/learning/sessions/models.py +162 -0
- thearc-0.1.0/thearc/learning/sessions/store.py +735 -0
- thearc-0.1.0/thearc/models/__init__.py +59 -0
- thearc-0.1.0/thearc/models/agent.py +706 -0
- thearc-0.1.0/thearc/models/diff.py +46 -0
- thearc-0.1.0/thearc/models/identity.py +107 -0
- thearc-0.1.0/thearc/models/markdown.py +303 -0
- thearc-0.1.0/thearc/models/ranks.py +33 -0
- thearc-0.1.0/thearc/models/schemas.py +93 -0
- thearc-0.1.0/thearc/models/session.py +471 -0
- thearc-0.1.0/thearc/models/strategies.py +134 -0
- thearc-0.1.0/thearc/models/tracker.py +302 -0
- thearc-0.1.0/thearc/models/workspace.py +158 -0
- thearc-0.1.0/thearc.egg-info/PKG-INFO +173 -0
- thearc-0.1.0/thearc.egg-info/SOURCES.txt +118 -0
- thearc-0.1.0/thearc.egg-info/dependency_links.txt +1 -0
- thearc-0.1.0/thearc.egg-info/entry_points.txt +2 -0
- thearc-0.1.0/thearc.egg-info/requires.txt +21 -0
- thearc-0.1.0/thearc.egg-info/top_level.txt +1 -0
thearc-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: thearc
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Agent-agnostic plugin & skill installer system for Codex, Claude, and Antigravity
|
|
5
|
+
Project-URL: Repository, https://github.com/micmurawski/thearc
|
|
6
|
+
Project-URL: Documentation, https://micmurawski.github.io/thearc/
|
|
7
|
+
Project-URL: Issues, https://github.com/micmurawski/thearc/issues
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
Requires-Dist: click>=8.0.0
|
|
11
|
+
Requires-Dist: pyyaml>=6.0
|
|
12
|
+
Requires-Dist: pydantic>=2.0.0
|
|
13
|
+
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
|
|
14
|
+
Provides-Extra: docs
|
|
15
|
+
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
|
|
16
|
+
Provides-Extra: codex
|
|
17
|
+
Requires-Dist: openai-codex==0.157.1; extra == "codex"
|
|
18
|
+
Provides-Extra: antigravity
|
|
19
|
+
Requires-Dist: google-antigravity==0.1.19; extra == "antigravity"
|
|
20
|
+
Provides-Extra: arrow
|
|
21
|
+
Requires-Dist: pyarrow>=14.0.0; extra == "arrow"
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: ruff>=0.8.0; extra == "dev"
|
|
24
|
+
|
|
25
|
+
# thearc ⚡
|
|
26
|
+
|
|
27
|
+
`thearc` is an extensible meta-framework for collecting and exploring episodic sessions from AI agents. Rather than prescribing one agent design, it provides the abstractions needed to turn agent traces into evidence for evaluating and improving an agentic system’s context files, skills, hooks, prompts, and MCP integrations.
|
|
28
|
+
|
|
29
|
+
Build agentic context-engineering pipelines on top of `thearc`: inspect sessions, extract reusable lessons and failures, curate versioned updates, evaluate their effect, and install the resulting capabilities into agent environments. The framework is designed to let these pipelines evolve as new artifacts and evaluation methods emerge, drawing direction from work on [agentic context engineering](https://arxiv.org/pdf/2510.04618), [meta-skill evolution](https://arxiv.org/pdf/2607.05297), [self-evolving agent skills](https://arxiv.org/pdf/2608.02636), [self-evolving agents](https://arxiv.org/html/2507.21046v4), and [meta context engineering](https://arxiv.org/pdf/2601.21557).
|
|
30
|
+
|
|
31
|
+
## A simple ACE example
|
|
32
|
+
|
|
33
|
+
Give it your configuration and a past session. Get back an adapted configuration,
|
|
34
|
+
with evidence explaining the changes. No flow engine or tracker—just reflection
|
|
35
|
+
followed by curation.
|
|
36
|
+
|
|
37
|
+
First, index your existing native session logs into a local SQLite database:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
thearc sessions --index sessions.sqlite index \
|
|
41
|
+
--source YOUR_SOURCE --source-id my-experiments \
|
|
42
|
+
--root /absolute/path/to/session/logs
|
|
43
|
+
thearc sessions --index sessions.sqlite list
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Replace `YOUR_SOURCE` with `antigravity`, `claude`, `codex`, or `pi` to match the
|
|
47
|
+
log format. Indexing reads existing logs; it does not run an agent or modify those
|
|
48
|
+
logs. To refresh registered sources later, run
|
|
49
|
+
`thearc sessions --index sessions.sqlite sync`.
|
|
50
|
+
|
|
51
|
+
Then select evidence and adapt the configuration:
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from datetime import datetime, timezone
|
|
55
|
+
from pathlib import Path
|
|
56
|
+
|
|
57
|
+
from thearc import MetaAgent
|
|
58
|
+
from thearc.learning import EvidenceSnapshot, SearchFilters, SessionStore
|
|
59
|
+
from thearc.learning.curation import create_curator, run_curation
|
|
60
|
+
from thearc.learning.evidence.snapshot import check_destination
|
|
61
|
+
from thearc.learning.reflection import ReflectorConfig, create_reflector
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def adapt(
|
|
65
|
+
agent: MetaAgent, evidence: EvidenceSnapshot, *, backend: str, model: str,
|
|
66
|
+
output: str | Path,
|
|
67
|
+
) -> MetaAgent:
|
|
68
|
+
"""Adapt one configuration from a small snapshot; preserve inputs and provenance."""
|
|
69
|
+
config = ReflectorConfig(model=model)
|
|
70
|
+
reflector = create_reflector(backend, config)
|
|
71
|
+
curator = create_curator(backend, config)
|
|
72
|
+
# Preflight before creating artifacts or invoking either runtime.
|
|
73
|
+
reflector.prepare_snapshot(evidence, agent)
|
|
74
|
+
output = check_destination(output, tuple(evidence.manifest["blocked_root_hashes"]))
|
|
75
|
+
output.mkdir(parents=True, mode=0o700)
|
|
76
|
+
agent.to_workspace(output / "baseline")
|
|
77
|
+
evidence.save(output / "evidence")
|
|
78
|
+
reflector.artifact_dir = output / "reflections"
|
|
79
|
+
|
|
80
|
+
reflection = reflector.reflect_snapshot(evidence, agent)
|
|
81
|
+
epoch = run_curation(agent, [reflection], curator, output=output / "curation")
|
|
82
|
+
return MetaAgent.model_validate(epoch["agent"])
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
agent = MetaAgent.from_workspace("my-agent")
|
|
86
|
+
|
|
87
|
+
# Sessions must already be ingested into this index.
|
|
88
|
+
cutoff = datetime(2026, 9, 1, tzinfo=timezone.utc)
|
|
89
|
+
with SessionStore("sessions.sqlite") as store:
|
|
90
|
+
evidence = store.snapshot(filters=SearchFilters(started_before=cutoff))
|
|
91
|
+
|
|
92
|
+
adapted = adapt(
|
|
93
|
+
agent, evidence,
|
|
94
|
+
backend="YOUR_BACKEND",
|
|
95
|
+
model="YOUR_MODEL_ID",
|
|
96
|
+
output="artifacts/first-ace-run",
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
print(agent.diff(adapted))
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Replace `YOUR_BACKEND` with `antigravity`, `claude`, or `codex`, and choose a model
|
|
103
|
+
supported by that runtime. Install/authenticate the runtime first; see
|
|
104
|
+
[runtime setup](docs/reference/runtimes.md#current-runtime-support). There is no
|
|
105
|
+
default provider, and the source-session format need not match the backend.
|
|
106
|
+
|
|
107
|
+
`my-agent` is a canonical workspace saved with `MetaAgent.to_workspace()`.
|
|
108
|
+
`sessions.sqlite` must already contain ingested sessions; see
|
|
109
|
+
[session ingestion](docs/guides/sessions.md). The example selects sessions
|
|
110
|
+
whose indexed `started_at` is **strictly before September 1, 2026, at midnight UTC**.
|
|
111
|
+
Change `cutoff` to your desired timezone-aware datetime. Indexed start times use
|
|
112
|
+
the earliest valid, timezone-aware event timestamp; sessions without one do not
|
|
113
|
+
match date filters. Filtering happens in SQLite across registered sources, without
|
|
114
|
+
a pagination limit. No matches produces a clear error. Use `SearchFilters()` to
|
|
115
|
+
snapshot all indexed sessions, or add `source_ids=["my-experiments"]` to limit scope.
|
|
116
|
+
|
|
117
|
+
This selects whole sessions by start time, not individual events: a selected
|
|
118
|
+
session may contain activity after the cutoff. It does not imply the session has
|
|
119
|
+
finished. Snapshotting does not ingest or refresh logs.
|
|
120
|
+
Pass the snapshot directly to `adapt()`; it saves the evidence under
|
|
121
|
+
`artifacts/first-ace-run/evidence`, so no intermediate save/load is necessary.
|
|
122
|
+
Later, reload it with `EvidenceSnapshot.load("artifacts/first-ace-run/evidence")`.
|
|
123
|
+
|
|
124
|
+
Use a small index containing sessions relevant to this configuration. Snapshot
|
|
125
|
+
storage and reflector input limits still apply; this example does not batch large
|
|
126
|
+
collections or guarantee that every event reaches the reflector. Use the
|
|
127
|
+
[batched cookbook](cookbook/README.md#visualized-batched-ace) for larger collections.
|
|
128
|
+
Use the configuration associated with those sessions where possible; the library
|
|
129
|
+
cannot prove which instructions were loaded during a historical session.
|
|
130
|
+
|
|
131
|
+
Calling `adapt()` invokes real agents and can consume quota. It preserves the
|
|
132
|
+
original configuration and saves the baseline, evidence, reflections, and committed
|
|
133
|
+
curation history in a new output directory. Existing output directories are refused.
|
|
134
|
+
Inspect the findings and changes with:
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
thearc reflection show artifacts/first-ace-run/reflections
|
|
138
|
+
thearc curation show artifacts/first-ace-run/curation
|
|
139
|
+
thearc curation diff artifacts/first-ace-run/curation
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Reflections rate specific configuration parts with reasons and citations; curation
|
|
143
|
+
uses those findings to make validated edits. A no-change result is valid. This
|
|
144
|
+
small-snapshot example does not replay session commands, install the result, run
|
|
145
|
+
evaluation, or bump the release version. An edit alone is not proof of improved
|
|
146
|
+
performance. Review artifacts for sensitive information before sharing.
|
|
147
|
+
|
|
148
|
+
The same function is available in [cookbook/simple_ace.py](cookbook/simple_ace.py).
|
|
149
|
+
|
|
150
|
+
### Install into multiple agents
|
|
151
|
+
|
|
152
|
+
The same `MetaAgent` can be installed for different agent harnesses, independently
|
|
153
|
+
of which backend produced it:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
for implementation in ("antigravity", "claude", "codex", "pi"):
|
|
157
|
+
adapted.install(implementation)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
These are separate project directories; use your project's path to install there.
|
|
161
|
+
Installation writes harness-specific configuration files, not agent executables,
|
|
162
|
+
and overwrites matching files by default. Review the diff before installing.
|
|
163
|
+
|
|
164
|
+
## Further reading
|
|
165
|
+
|
|
166
|
+
Browse the [documentation](docs/index.md), or preview the MkDocs site locally:
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
python -m pip install -e '.[docs]'
|
|
170
|
+
python -m mkdocs serve
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
For runnable evidence, reflection, and handoff examples, see the [cookbook](cookbook/README.md).
|
thearc-0.1.0/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# thearc ⚡
|
|
2
|
+
|
|
3
|
+
`thearc` is an extensible meta-framework for collecting and exploring episodic sessions from AI agents. Rather than prescribing one agent design, it provides the abstractions needed to turn agent traces into evidence for evaluating and improving an agentic system’s context files, skills, hooks, prompts, and MCP integrations.
|
|
4
|
+
|
|
5
|
+
Build agentic context-engineering pipelines on top of `thearc`: inspect sessions, extract reusable lessons and failures, curate versioned updates, evaluate their effect, and install the resulting capabilities into agent environments. The framework is designed to let these pipelines evolve as new artifacts and evaluation methods emerge, drawing direction from work on [agentic context engineering](https://arxiv.org/pdf/2510.04618), [meta-skill evolution](https://arxiv.org/pdf/2607.05297), [self-evolving agent skills](https://arxiv.org/pdf/2608.02636), [self-evolving agents](https://arxiv.org/html/2507.21046v4), and [meta context engineering](https://arxiv.org/pdf/2601.21557).
|
|
6
|
+
|
|
7
|
+
## A simple ACE example
|
|
8
|
+
|
|
9
|
+
Give it your configuration and a past session. Get back an adapted configuration,
|
|
10
|
+
with evidence explaining the changes. No flow engine or tracker—just reflection
|
|
11
|
+
followed by curation.
|
|
12
|
+
|
|
13
|
+
First, index your existing native session logs into a local SQLite database:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
thearc sessions --index sessions.sqlite index \
|
|
17
|
+
--source YOUR_SOURCE --source-id my-experiments \
|
|
18
|
+
--root /absolute/path/to/session/logs
|
|
19
|
+
thearc sessions --index sessions.sqlite list
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Replace `YOUR_SOURCE` with `antigravity`, `claude`, `codex`, or `pi` to match the
|
|
23
|
+
log format. Indexing reads existing logs; it does not run an agent or modify those
|
|
24
|
+
logs. To refresh registered sources later, run
|
|
25
|
+
`thearc sessions --index sessions.sqlite sync`.
|
|
26
|
+
|
|
27
|
+
Then select evidence and adapt the configuration:
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from datetime import datetime, timezone
|
|
31
|
+
from pathlib import Path
|
|
32
|
+
|
|
33
|
+
from thearc import MetaAgent
|
|
34
|
+
from thearc.learning import EvidenceSnapshot, SearchFilters, SessionStore
|
|
35
|
+
from thearc.learning.curation import create_curator, run_curation
|
|
36
|
+
from thearc.learning.evidence.snapshot import check_destination
|
|
37
|
+
from thearc.learning.reflection import ReflectorConfig, create_reflector
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def adapt(
|
|
41
|
+
agent: MetaAgent, evidence: EvidenceSnapshot, *, backend: str, model: str,
|
|
42
|
+
output: str | Path,
|
|
43
|
+
) -> MetaAgent:
|
|
44
|
+
"""Adapt one configuration from a small snapshot; preserve inputs and provenance."""
|
|
45
|
+
config = ReflectorConfig(model=model)
|
|
46
|
+
reflector = create_reflector(backend, config)
|
|
47
|
+
curator = create_curator(backend, config)
|
|
48
|
+
# Preflight before creating artifacts or invoking either runtime.
|
|
49
|
+
reflector.prepare_snapshot(evidence, agent)
|
|
50
|
+
output = check_destination(output, tuple(evidence.manifest["blocked_root_hashes"]))
|
|
51
|
+
output.mkdir(parents=True, mode=0o700)
|
|
52
|
+
agent.to_workspace(output / "baseline")
|
|
53
|
+
evidence.save(output / "evidence")
|
|
54
|
+
reflector.artifact_dir = output / "reflections"
|
|
55
|
+
|
|
56
|
+
reflection = reflector.reflect_snapshot(evidence, agent)
|
|
57
|
+
epoch = run_curation(agent, [reflection], curator, output=output / "curation")
|
|
58
|
+
return MetaAgent.model_validate(epoch["agent"])
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
agent = MetaAgent.from_workspace("my-agent")
|
|
62
|
+
|
|
63
|
+
# Sessions must already be ingested into this index.
|
|
64
|
+
cutoff = datetime(2026, 9, 1, tzinfo=timezone.utc)
|
|
65
|
+
with SessionStore("sessions.sqlite") as store:
|
|
66
|
+
evidence = store.snapshot(filters=SearchFilters(started_before=cutoff))
|
|
67
|
+
|
|
68
|
+
adapted = adapt(
|
|
69
|
+
agent, evidence,
|
|
70
|
+
backend="YOUR_BACKEND",
|
|
71
|
+
model="YOUR_MODEL_ID",
|
|
72
|
+
output="artifacts/first-ace-run",
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
print(agent.diff(adapted))
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Replace `YOUR_BACKEND` with `antigravity`, `claude`, or `codex`, and choose a model
|
|
79
|
+
supported by that runtime. Install/authenticate the runtime first; see
|
|
80
|
+
[runtime setup](docs/reference/runtimes.md#current-runtime-support). There is no
|
|
81
|
+
default provider, and the source-session format need not match the backend.
|
|
82
|
+
|
|
83
|
+
`my-agent` is a canonical workspace saved with `MetaAgent.to_workspace()`.
|
|
84
|
+
`sessions.sqlite` must already contain ingested sessions; see
|
|
85
|
+
[session ingestion](docs/guides/sessions.md). The example selects sessions
|
|
86
|
+
whose indexed `started_at` is **strictly before September 1, 2026, at midnight UTC**.
|
|
87
|
+
Change `cutoff` to your desired timezone-aware datetime. Indexed start times use
|
|
88
|
+
the earliest valid, timezone-aware event timestamp; sessions without one do not
|
|
89
|
+
match date filters. Filtering happens in SQLite across registered sources, without
|
|
90
|
+
a pagination limit. No matches produces a clear error. Use `SearchFilters()` to
|
|
91
|
+
snapshot all indexed sessions, or add `source_ids=["my-experiments"]` to limit scope.
|
|
92
|
+
|
|
93
|
+
This selects whole sessions by start time, not individual events: a selected
|
|
94
|
+
session may contain activity after the cutoff. It does not imply the session has
|
|
95
|
+
finished. Snapshotting does not ingest or refresh logs.
|
|
96
|
+
Pass the snapshot directly to `adapt()`; it saves the evidence under
|
|
97
|
+
`artifacts/first-ace-run/evidence`, so no intermediate save/load is necessary.
|
|
98
|
+
Later, reload it with `EvidenceSnapshot.load("artifacts/first-ace-run/evidence")`.
|
|
99
|
+
|
|
100
|
+
Use a small index containing sessions relevant to this configuration. Snapshot
|
|
101
|
+
storage and reflector input limits still apply; this example does not batch large
|
|
102
|
+
collections or guarantee that every event reaches the reflector. Use the
|
|
103
|
+
[batched cookbook](cookbook/README.md#visualized-batched-ace) for larger collections.
|
|
104
|
+
Use the configuration associated with those sessions where possible; the library
|
|
105
|
+
cannot prove which instructions were loaded during a historical session.
|
|
106
|
+
|
|
107
|
+
Calling `adapt()` invokes real agents and can consume quota. It preserves the
|
|
108
|
+
original configuration and saves the baseline, evidence, reflections, and committed
|
|
109
|
+
curation history in a new output directory. Existing output directories are refused.
|
|
110
|
+
Inspect the findings and changes with:
|
|
111
|
+
|
|
112
|
+
```sh
|
|
113
|
+
thearc reflection show artifacts/first-ace-run/reflections
|
|
114
|
+
thearc curation show artifacts/first-ace-run/curation
|
|
115
|
+
thearc curation diff artifacts/first-ace-run/curation
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Reflections rate specific configuration parts with reasons and citations; curation
|
|
119
|
+
uses those findings to make validated edits. A no-change result is valid. This
|
|
120
|
+
small-snapshot example does not replay session commands, install the result, run
|
|
121
|
+
evaluation, or bump the release version. An edit alone is not proof of improved
|
|
122
|
+
performance. Review artifacts for sensitive information before sharing.
|
|
123
|
+
|
|
124
|
+
The same function is available in [cookbook/simple_ace.py](cookbook/simple_ace.py).
|
|
125
|
+
|
|
126
|
+
### Install into multiple agents
|
|
127
|
+
|
|
128
|
+
The same `MetaAgent` can be installed for different agent harnesses, independently
|
|
129
|
+
of which backend produced it:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
for implementation in ("antigravity", "claude", "codex", "pi"):
|
|
133
|
+
adapted.install(implementation)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
These are separate project directories; use your project's path to install there.
|
|
137
|
+
Installation writes harness-specific configuration files, not agent executables,
|
|
138
|
+
and overwrites matching files by default. Review the diff before installing.
|
|
139
|
+
|
|
140
|
+
## Further reading
|
|
141
|
+
|
|
142
|
+
Browse the [documentation](docs/index.md), or preview the MkDocs site locally:
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
python -m pip install -e '.[docs]'
|
|
146
|
+
python -m mkdocs serve
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
For runnable evidence, reflection, and handoff examples, see the [cookbook](cookbook/README.md).
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "thearc"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Agent-agnostic plugin & skill installer system for Codex, Claude, and Antigravity"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
dependencies = [
|
|
12
|
+
"click>=8.0.0",
|
|
13
|
+
"pyyaml>=6.0",
|
|
14
|
+
"pydantic>=2.0.0",
|
|
15
|
+
"tomli>=1.1.0; python_version < '3.11'",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.scripts]
|
|
19
|
+
thearc = "thearc.cli:main"
|
|
20
|
+
|
|
21
|
+
[project.urls]
|
|
22
|
+
Repository = "https://github.com/micmurawski/thearc"
|
|
23
|
+
Documentation = "https://micmurawski.github.io/thearc/"
|
|
24
|
+
Issues = "https://github.com/micmurawski/thearc/issues"
|
|
25
|
+
|
|
26
|
+
[tool.setuptools.packages.find]
|
|
27
|
+
include = ["thearc*"]
|
|
28
|
+
|
|
29
|
+
[tool.setuptools.package-data]
|
|
30
|
+
"thearc.flow" = ["viz.css", "viz.js"]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
docs = ["mkdocs>=1.6,<2"]
|
|
34
|
+
codex = ["openai-codex==0.157.1"]
|
|
35
|
+
antigravity = ["google-antigravity==0.1.19"]
|
|
36
|
+
arrow = ["pyarrow>=14.0.0"]
|
|
37
|
+
dev = [
|
|
38
|
+
"ruff>=0.8.0",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
[tool.pytest.ini_options]
|
|
42
|
+
testpaths = ["tests"]
|
|
43
|
+
norecursedirs = [".*", "build", "dist", "*.egg", "node_modules", "venv", "fastapi"]
|
|
44
|
+
|
|
45
|
+
[tool.ruff]
|
|
46
|
+
line-length = 120
|
|
47
|
+
target-version = "py310"
|
|
48
|
+
extend-exclude = ["tests/fastapi"]
|
|
49
|
+
|
|
50
|
+
[tool.ruff.lint]
|
|
51
|
+
extend-select = ["E501"]
|
thearc-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
from thearc import MetaAgent, Operation, ResourceTarget, Skill
|
|
2
|
+
from thearc.learning import (
|
|
3
|
+
AceConfig,
|
|
4
|
+
AcePipeline,
|
|
5
|
+
Curation,
|
|
6
|
+
Reflection,
|
|
7
|
+
Session,
|
|
8
|
+
TaskScore,
|
|
9
|
+
build_ace_flow,
|
|
10
|
+
)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def session(number):
|
|
14
|
+
return Session(id=f"s{number}", source_id="source", harness="pi", native_id=f"native-{number}")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class Selector:
|
|
18
|
+
def select(self, filters=None):
|
|
19
|
+
return [session(number) for number in range(5)]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class Materializer:
|
|
23
|
+
def materialize(self, session, config):
|
|
24
|
+
from thearc.learning import SessionBundle
|
|
25
|
+
|
|
26
|
+
return SessionBundle(session=session)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class Reflector:
|
|
30
|
+
def __init__(self):
|
|
31
|
+
self.batches = []
|
|
32
|
+
|
|
33
|
+
def reflect(self, batch, target):
|
|
34
|
+
self.batches.append(batch)
|
|
35
|
+
return Reflection(id=f"r{len(self.batches)}", session_ids=[item.session.id for item in batch])
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class Curator:
|
|
39
|
+
def __init__(self):
|
|
40
|
+
self.batches = []
|
|
41
|
+
|
|
42
|
+
def curate(self, batch, agent):
|
|
43
|
+
self.batches.append(batch)
|
|
44
|
+
return [Curation(
|
|
45
|
+
id=f"c{len(self.batches)}",
|
|
46
|
+
target=ResourceTarget(kind="skill", name="demo"),
|
|
47
|
+
operation=Operation.EDIT,
|
|
48
|
+
value={"description": "Updated"},
|
|
49
|
+
reflection_ids=[item.id for item in batch],
|
|
50
|
+
rationale="Update guidance based on session evidence",
|
|
51
|
+
)]
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def test_pipeline_batches_sessions_and_updates_once():
|
|
56
|
+
reflector = Reflector()
|
|
57
|
+
curator = Curator()
|
|
58
|
+
result = AcePipeline(
|
|
59
|
+
Selector(),
|
|
60
|
+
Materializer(),
|
|
61
|
+
reflector,
|
|
62
|
+
curator,
|
|
63
|
+
AceConfig(sessions_per_reflection=2, reflections_per_curation=2),
|
|
64
|
+
).run(agent=MetaAgent(name="agent", skills=[Skill(name="demo")]))
|
|
65
|
+
|
|
66
|
+
assert len(result.sessions) == 5
|
|
67
|
+
assert [len(batch) for batch in reflector.batches] == [2, 2, 1]
|
|
68
|
+
assert [len(batch) for batch in curator.batches] == [2, 1]
|
|
69
|
+
assert result.update.applied_curation_ids == [item.id for item in result.curations]
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def test_flow_exposes_the_same_stages():
|
|
73
|
+
reflector = Reflector()
|
|
74
|
+
curator = Curator()
|
|
75
|
+
shared = {
|
|
76
|
+
"selector": Selector(),
|
|
77
|
+
"materializer": Materializer(),
|
|
78
|
+
"reflector": reflector,
|
|
79
|
+
"curator": curator,
|
|
80
|
+
"config": AceConfig(sessions_per_reflection=2, reflections_per_curation=2),
|
|
81
|
+
"agent": MetaAgent(name="agent", skills=[Skill(name="demo")]),
|
|
82
|
+
}
|
|
83
|
+
build_ace_flow().run(shared)
|
|
84
|
+
assert len(reflector.batches) == 3
|
|
85
|
+
assert len(curator.batches) == 2
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def test_only_accepted_changes_reach_next_batch_and_are_applied_once(monkeypatch):
|
|
89
|
+
calls, recorded = [], []
|
|
90
|
+
original_apply = MetaAgent.apply_change
|
|
91
|
+
|
|
92
|
+
def counted_apply(self, target, operation, value=None):
|
|
93
|
+
calls.append(target)
|
|
94
|
+
return original_apply(self, target, operation, value)
|
|
95
|
+
|
|
96
|
+
monkeypatch.setattr(MetaAgent, "apply_change", counted_apply)
|
|
97
|
+
|
|
98
|
+
class CheckingCurator:
|
|
99
|
+
def __init__(self):
|
|
100
|
+
self.index = 0
|
|
101
|
+
|
|
102
|
+
def curate(self, batch, agent):
|
|
103
|
+
self.index += 1
|
|
104
|
+
assert "rejected" not in agent.hooks
|
|
105
|
+
if self.index == 1:
|
|
106
|
+
return [Curation(
|
|
107
|
+
id="reject", target=ResourceTarget(kind="hook", name="rejected"),
|
|
108
|
+
operation=Operation.ADD, value={"command": "echo bad"},
|
|
109
|
+
reflection_ids=[batch[0].id], rationale=" ",
|
|
110
|
+
)]
|
|
111
|
+
if self.index > 2:
|
|
112
|
+
assert agent.skills["demo"].description == str(self.index - 1)
|
|
113
|
+
return [Curation(
|
|
114
|
+
id=str(self.index), target=ResourceTarget(kind="skill", name="demo"),
|
|
115
|
+
operation=Operation.EDIT, value={"description": str(self.index)},
|
|
116
|
+
reflection_ids=[batch[0].id], rationale="Session evidence",
|
|
117
|
+
)]
|
|
118
|
+
|
|
119
|
+
source = MetaAgent(name="agent", skills=[Skill(name="demo")])
|
|
120
|
+
result = AcePipeline(
|
|
121
|
+
Selector(), Materializer(), Reflector(), CheckingCurator(),
|
|
122
|
+
AceConfig(sessions_per_reflection=1, reflections_per_curation=1),
|
|
123
|
+
on_change=lambda change, before, after: recorded.append(change.id),
|
|
124
|
+
).run(source)
|
|
125
|
+
assert len(calls) == 4
|
|
126
|
+
assert recorded == ["2", "3", "4", "5"]
|
|
127
|
+
assert result.update.rejected_curation_ids == ["reject"]
|
|
128
|
+
assert result.agent.skills["demo"].description == "5"
|
|
129
|
+
assert source.skills["demo"].description == ""
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def test_pipeline_evaluates_original_and_result_on_held_out_tasks():
|
|
133
|
+
source = MetaAgent(name="agent", skills=[Skill(name="demo")])
|
|
134
|
+
evaluated = []
|
|
135
|
+
|
|
136
|
+
def evaluate(agent, task):
|
|
137
|
+
description = agent.skills["demo"].description
|
|
138
|
+
evaluated.append((description, task))
|
|
139
|
+
return TaskScore(success=description == "Updated", cost=1, latency_seconds=2)
|
|
140
|
+
|
|
141
|
+
pipeline = AcePipeline(Selector(), Materializer(), Reflector(), Curator())
|
|
142
|
+
result = pipeline.run(source, evaluation_tasks={"held-out": "Check instructions"}, evaluator=evaluate)
|
|
143
|
+
assert evaluated == [("", "Check instructions"), ("Updated", "Check instructions")]
|
|
144
|
+
assert result.evaluation.summary["delta"]["success_rate"] == 1
|
|
145
|
+
assert source.skills["demo"].description == ""
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
from pydantic import ValidationError
|
|
3
|
+
|
|
4
|
+
from thearc import MetaAgent, Skill
|
|
5
|
+
from thearc.learning import EvaluationResult, TaskScore, compare_agents
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def test_same_held_out_tasks_isolation_and_metric_deltas():
|
|
9
|
+
baseline = MetaAgent(name="baseline", skills=[Skill(name="demo")])
|
|
10
|
+
candidate = baseline.model_copy(deep=True)
|
|
11
|
+
candidate.skills["demo"].description = "improved"
|
|
12
|
+
tasks = {"holdout-a": {"prompt": "a"}, "holdout-b": {"prompt": "b"}}
|
|
13
|
+
calls = []
|
|
14
|
+
|
|
15
|
+
def evaluate(agent, task):
|
|
16
|
+
improved = bool(agent.skills["demo"].description)
|
|
17
|
+
calls.append((task["prompt"], improved))
|
|
18
|
+
agent.skills.clear()
|
|
19
|
+
task.clear()
|
|
20
|
+
return TaskScore(success=improved, cost=2 if improved else 1, latency_seconds=3 if improved else 5)
|
|
21
|
+
|
|
22
|
+
result = compare_agents(baseline, candidate, tasks, evaluate, training_task_ids=["training"])
|
|
23
|
+
assert calls == [("a", False), ("a", True), ("b", True), ("b", False)]
|
|
24
|
+
assert result.summary["delta"] == {"success_rate": 1, "mean_cost": 1, "mean_latency_seconds": -2}
|
|
25
|
+
assert tasks["holdout-a"] == {"prompt": "a"}
|
|
26
|
+
assert baseline.skills["demo"].description == ""
|
|
27
|
+
assert candidate.skills["demo"].description == "improved"
|
|
28
|
+
assert EvaluationResult.model_validate_json(result.model_dump_json()) == result
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def test_invalid_or_overlapping_evaluation_is_rejected_before_execution():
|
|
32
|
+
def must_not_run(*args):
|
|
33
|
+
pytest.fail("evaluation must not execute")
|
|
34
|
+
|
|
35
|
+
with pytest.raises(ValueError, match="overlap"):
|
|
36
|
+
compare_agents(
|
|
37
|
+
MetaAgent(name="agent"), MetaAgent(name="agent"), {"same": "task"},
|
|
38
|
+
must_not_run, training_task_ids=["same"],
|
|
39
|
+
)
|
|
40
|
+
with pytest.raises(ValueError, match="at least one"):
|
|
41
|
+
compare_agents(MetaAgent(name="agent"), MetaAgent(name="agent"), {}, must_not_run)
|
|
42
|
+
with pytest.raises(ValidationError):
|
|
43
|
+
TaskScore(success=True, cost=float("nan"), latency_seconds=1)
|
|
44
|
+
with pytest.raises(ValidationError):
|
|
45
|
+
EvaluationResult(baseline={}, candidate={})
|