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.
Files changed (120) hide show
  1. thearc-0.1.0/PKG-INFO +173 -0
  2. thearc-0.1.0/README.md +149 -0
  3. thearc-0.1.0/pyproject.toml +51 -0
  4. thearc-0.1.0/setup.cfg +4 -0
  5. thearc-0.1.0/tests/test_ace.py +145 -0
  6. thearc-0.1.0/tests/test_ace_evaluation.py +45 -0
  7. thearc-0.1.0/tests/test_ace_toy.py +185 -0
  8. thearc-0.1.0/tests/test_agent_class.py +289 -0
  9. thearc-0.1.0/tests/test_agent_reflectors.py +240 -0
  10. thearc-0.1.0/tests/test_agents.py +39 -0
  11. thearc-0.1.0/tests/test_cli.py +48 -0
  12. thearc-0.1.0/tests/test_codex_reflector.py +510 -0
  13. thearc-0.1.0/tests/test_config.py +49 -0
  14. thearc-0.1.0/tests/test_cookbook.py +242 -0
  15. thearc-0.1.0/tests/test_cookbook_ace_flow.py +136 -0
  16. thearc-0.1.0/tests/test_curation_assessments.py +174 -0
  17. thearc-0.1.0/tests/test_curation_backends.py +167 -0
  18. thearc-0.1.0/tests/test_curation_flow.py +195 -0
  19. thearc-0.1.0/tests/test_curation_targets.py +106 -0
  20. thearc-0.1.0/tests/test_documentation.py +67 -0
  21. thearc-0.1.0/tests/test_evidence.py +301 -0
  22. thearc-0.1.0/tests/test_graphify_installation.py +115 -0
  23. thearc-0.1.0/tests/test_history.py +479 -0
  24. thearc-0.1.0/tests/test_history_exports.py +45 -0
  25. thearc-0.1.0/tests/test_learning_layout.py +90 -0
  26. thearc-0.1.0/tests/test_metaagent_diff.py +112 -0
  27. thearc-0.1.0/tests/test_metaagent_identity.py +194 -0
  28. thearc-0.1.0/tests/test_metaagent_workspace.py +109 -0
  29. thearc-0.1.0/tests/test_models.py +105 -0
  30. thearc-0.1.0/tests/test_package_support.py +25 -0
  31. thearc-0.1.0/tests/test_prompt_collection.py +193 -0
  32. thearc-0.1.0/tests/test_ranks.py +118 -0
  33. thearc-0.1.0/tests/test_reflection_cli.py +105 -0
  34. thearc-0.1.0/tests/test_reflections_flow.py +145 -0
  35. thearc-0.1.0/tests/test_reflector.py +141 -0
  36. thearc-0.1.0/tests/test_release_workflow.py +27 -0
  37. thearc-0.1.0/tests/test_scaling_selection.py +139 -0
  38. thearc-0.1.0/tests/test_session_date_filters.py +173 -0
  39. thearc-0.1.0/tests/test_session_search.py +77 -0
  40. thearc-0.1.0/tests/test_tracker.py +114 -0
  41. thearc-0.1.0/thearc/__init__.py +34 -0
  42. thearc-0.1.0/thearc/agents/__init__.py +26 -0
  43. thearc-0.1.0/thearc/agents/antigravity.py +8 -0
  44. thearc-0.1.0/thearc/agents/base.py +442 -0
  45. thearc-0.1.0/thearc/agents/claude.py +8 -0
  46. thearc-0.1.0/thearc/agents/codex.py +8 -0
  47. thearc-0.1.0/thearc/agents/pi.py +8 -0
  48. thearc-0.1.0/thearc/cli.py +23 -0
  49. thearc-0.1.0/thearc/config.py +173 -0
  50. thearc-0.1.0/thearc/flow/__init__.py +108 -0
  51. thearc-0.1.0/thearc/flow/decorators.py +380 -0
  52. thearc-0.1.0/thearc/flow/test.py +128 -0
  53. thearc-0.1.0/thearc/flow/utils.py +248 -0
  54. thearc-0.1.0/thearc/flow/viz.css +433 -0
  55. thearc-0.1.0/thearc/flow/viz.js +259 -0
  56. thearc-0.1.0/thearc/flow/viz.py +656 -0
  57. thearc-0.1.0/thearc/learning/__init__.py +145 -0
  58. thearc-0.1.0/thearc/learning/_compat.py +39 -0
  59. thearc-0.1.0/thearc/learning/ace/__init__.py +35 -0
  60. thearc-0.1.0/thearc/learning/ace/evaluation.py +70 -0
  61. thearc-0.1.0/thearc/learning/ace/pipeline.py +425 -0
  62. thearc-0.1.0/thearc/learning/ace/toy.py +262 -0
  63. thearc-0.1.0/thearc/learning/cli.py +25 -0
  64. thearc-0.1.0/thearc/learning/curation/__init__.py +22 -0
  65. thearc-0.1.0/thearc/learning/curation/assessments.py +182 -0
  66. thearc-0.1.0/thearc/learning/curation/cli.py +115 -0
  67. thearc-0.1.0/thearc/learning/curation/engine.py +182 -0
  68. thearc-0.1.0/thearc/learning/curation/epochs.py +121 -0
  69. thearc-0.1.0/thearc/learning/curation/factory.py +41 -0
  70. thearc-0.1.0/thearc/learning/curation/providers/__init__.py +10 -0
  71. thearc-0.1.0/thearc/learning/curation/providers/antigravity.py +16 -0
  72. thearc-0.1.0/thearc/learning/curation/providers/claude.py +15 -0
  73. thearc-0.1.0/thearc/learning/curation/providers/codex.py +21 -0
  74. thearc-0.1.0/thearc/learning/curation/structured.py +84 -0
  75. thearc-0.1.0/thearc/learning/curation/tools.py +210 -0
  76. thearc-0.1.0/thearc/learning/evidence/__init__.py +18 -0
  77. thearc-0.1.0/thearc/learning/evidence/cli.py +72 -0
  78. thearc-0.1.0/thearc/learning/evidence/exports.py +77 -0
  79. thearc-0.1.0/thearc/learning/evidence/snapshot.py +271 -0
  80. thearc-0.1.0/thearc/learning/evidence/tools.py +253 -0
  81. thearc-0.1.0/thearc/learning/privacy.py +61 -0
  82. thearc-0.1.0/thearc/learning/reflection/__init__.py +16 -0
  83. thearc-0.1.0/thearc/learning/reflection/backend.py +49 -0
  84. thearc-0.1.0/thearc/learning/reflection/cli.py +91 -0
  85. thearc-0.1.0/thearc/learning/reflection/engine.py +374 -0
  86. thearc-0.1.0/thearc/learning/reflection/factory.py +54 -0
  87. thearc-0.1.0/thearc/learning/reflection/flow.py +192 -0
  88. thearc-0.1.0/thearc/learning/reflection/providers/__init__.py +1 -0
  89. thearc-0.1.0/thearc/learning/reflection/providers/antigravity.py +127 -0
  90. thearc-0.1.0/thearc/learning/reflection/providers/claude.py +122 -0
  91. thearc-0.1.0/thearc/learning/reflection/providers/cli.py +65 -0
  92. thearc-0.1.0/thearc/learning/reflection/providers/codex.py +191 -0
  93. thearc-0.1.0/thearc/learning/runtime/__init__.py +9 -0
  94. thearc-0.1.0/thearc/learning/runtime/cli.py +42 -0
  95. thearc-0.1.0/thearc/learning/runtime/contracts.py +69 -0
  96. thearc-0.1.0/thearc/learning/runtime/handoff.py +152 -0
  97. thearc-0.1.0/thearc/learning/runtime/journal.py +148 -0
  98. thearc-0.1.0/thearc/learning/sessions/__init__.py +22 -0
  99. thearc-0.1.0/thearc/learning/sessions/adapters.py +473 -0
  100. thearc-0.1.0/thearc/learning/sessions/cli.py +107 -0
  101. thearc-0.1.0/thearc/learning/sessions/columnar.py +107 -0
  102. thearc-0.1.0/thearc/learning/sessions/models.py +162 -0
  103. thearc-0.1.0/thearc/learning/sessions/store.py +735 -0
  104. thearc-0.1.0/thearc/models/__init__.py +59 -0
  105. thearc-0.1.0/thearc/models/agent.py +706 -0
  106. thearc-0.1.0/thearc/models/diff.py +46 -0
  107. thearc-0.1.0/thearc/models/identity.py +107 -0
  108. thearc-0.1.0/thearc/models/markdown.py +303 -0
  109. thearc-0.1.0/thearc/models/ranks.py +33 -0
  110. thearc-0.1.0/thearc/models/schemas.py +93 -0
  111. thearc-0.1.0/thearc/models/session.py +471 -0
  112. thearc-0.1.0/thearc/models/strategies.py +134 -0
  113. thearc-0.1.0/thearc/models/tracker.py +302 -0
  114. thearc-0.1.0/thearc/models/workspace.py +158 -0
  115. thearc-0.1.0/thearc.egg-info/PKG-INFO +173 -0
  116. thearc-0.1.0/thearc.egg-info/SOURCES.txt +118 -0
  117. thearc-0.1.0/thearc.egg-info/dependency_links.txt +1 -0
  118. thearc-0.1.0/thearc.egg-info/entry_points.txt +2 -0
  119. thearc-0.1.0/thearc.egg-info/requires.txt +21 -0
  120. 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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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={})