archforge-optimizer 0.1.0__tar.gz → 0.2.0__tar.gz

{archforge_optimizer-0.1.0 → archforge_optimizer-0.2.0}/.gitignore

@@ -9,4 +9,4 @@ tests/
 # Keep the user-editable config (archforge.py) and suite (suite.json) trackable though.
 .archforge/*
 !.archforge/archforge.py
-!.archforge/suite.json
+!.archforge/suite.jsondist/

{archforge_optimizer-0.1.0 → archforge_optimizer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: archforge-optimizer
-Version: 0.1.0
+Version: 0.2.0
 Summary: ArchForge — a self-improving meta-layer over multi-agent systems
 License-Expression: MIT
 License-File: LICENSE
@@ -30,10 +30,19 @@ Description-Content-Type: text/markdown
 
 # ArchForge
 
+<p align="center">
+  <img src="images/logo.png" width="160">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg">
+</p>
+
 > A self-improving meta-layer over multi-agent systems.
 > Point it at your graph, give it a rubric, and it evolves your pipeline — one proven change per cycle.
 
-**Python ≥ 3.11** · **zero hard deps beyond pydantic** · **MIT-licensed** · install from PyPI with `pip install archforge-optimizer` · exercised end-to-end on a real LangGraph MAS (groq + google-genai + chroma, OpenTelemetry-traced).
+**Minimal core dependencies · optional provider and tracing integrations** · install from PyPI with `pip install archforge-optimizer` · exercised end-to-end on a real LangGraph MAS (groq + google-genai + chroma, OpenTelemetry-traced).
 
 ArchForge sits **on top** of an existing multi-agent system (MAS) and improves it run-over-run. Each cycle it inspects where the judge docked points, proposes **one** targeted change — rewriting an agent's prompt, tuning a knob, adding a verifier, re-wiring a node, swapping a model — and keeps it only if it measurably beats the incumbent on a held-out suite. The host MAS keeps running tasks as normal; ArchForge observes the runs and feeds back an improved pipeline.
 
@@ -119,8 +128,8 @@ with tempfile.TemporaryDirectory() as d:
 ```
 
 ```
-$ archforge-optimizer init       # once — scaffolds the project config the Engine reads
-$ python evolve_demo.py
+archforge-optimizer init       # once — scaffolds project config + the archforge_optimizer/ adapter package
+python evolve_demo.py
 action=AUTO_PROMOTE  margin=+0.15
 incumbent_mean=0.55  candidate_mean=0.70
 active_spec_id=57396a49  promoted=True
@@ -194,25 +203,29 @@ pip install archforge-optimizer
 # Optional: install the provider SDK(s) you actually run (none required to import)
 pip install "archforge-optimizer[providers-groq,providers-gemini]"
 
-# 2. Scaffold per-project config — writes .archforge/archforge.py (tunables),
-#    .archforge/suite.json (the eval tasks), .env.example (key template)
+# 2. Scaffold per-project config + the adapter package — writes:
+#      .archforge/archforge.py        (tunables — ACTIVE sane defaults)
+#      .archforge/suite.json          (the eval tasks you optimize against)
+#      archforge_optimizer/           (a generic LangGraph adapter skeleton — 5 files)
+#        __init__.py  host.py  app.py  sidecar.py  test_smoke_offline.py
 archforge-optimizer init
 
-# 3. Put your API keys in .env (gitignored)  ── e.g. GROQ_API_KEY=..., GEMINI_API_KEY=...
+# 3. Put your provider API key in a root `.env` (gitignored)  ── e.g. GEMINI_API_KEY=...
+#    (init never writes or touches .env — it just tells you to put the key there.)
 
-# 4. Lint a Spec before running it — checks DAG validity, node refs, type rules
-archforge-optimizer lint path/to/spec.json
+# 4. Edit your MAS details into archforge_optimizer/app.py — fill every `# EDIT:` marker
+#    (the node roster, edges, knobs, summarize/apply_llm_config hooks). Then build the
+#    bootstrap Spec from your EDITED adapter: it lints the roster first and writes
+#    archforge_optimizer/spec.json only if valid (rc=1 + the faults if not — fix + rerun).
+archforge-optimizer make-spec     # → archforge_optimizer/spec.json (lint OK)
 
-# 5. Run one Propose-Evaluate-Commit cycle against your MAS, wired by an adapter
-archforge-optimizer evolve \
-    --adapter your_pkg.your_host:YourAdapter \
-    --seed your_spec.json
+# 5. Run one Propose-Evaluate-Commit cycle against your MAS. evolve auto-defaults
+#    --adapter archforge_optimizer.host:AppAdapter and --seed archforge_optimizer/spec.json
+archforge-optimizer evolve
 
 # 6. Run the full loop: repeat evolve until K consecutive non-promotions (plateau)
-#    or a cycle/budget cap is hit
-archforge-optimizer evolve-loop \
-    --adapter your_pkg.your_host:YourAdapter \
-    --seed your_spec.json --max-cycles 50
+# or set flags in archforge.py
+archforge-optimizer evolve-loop --max-cycles 50
 
 # 7. Inspect
 archforge-optimizer status     # print the active incumbent Spec id, lineage, counts
@@ -220,11 +233,15 @@ archforge-optimizer report     # print per-attempt score deltas (incumbent vs ca
 archforge-optimizer approve --all   # move PENDING_HUMAN structural wins into active
 ```
 
+> `init` never writes `.env.example` or `spec.json` — the provider key lives in your root
+> `.env` (gitignored), and `spec.json` comes from `make-spec` (your real roster, linted),
+> not a template. Lint any Spec by hand with `archforge-optimizer lint path/to/spec.json`.
+
 > You can also invoke as `python -m archforge ...` — identical surface.
 >
 > **From source (development).** Clone the repo and `pip install -e .` for an editable install.
 
-The `--provider` flag selects the LLM backing the Architect + Judge (`scripted` by default for zero-cost runs; `anthropic` / `openai` / `groq` / `gemini` for real runs). The host MAS is wired via `--adapter my_pkg.my_host:MyAdapter`.
+The `--provider` flag selects the LLM backing the Architect + Judge (`anthropic` / `openai` / `groq` / `gemini` for real runs). The host MAS is wired via `--adapter my_pkg.my_host:MyAdapter` — and after `init`, `evolve` already defaults it to the `archforge_optimizer.host:AppAdapter`, so you only pass the flag for a custom adapter.
 
 ---
 
@@ -273,10 +290,12 @@ Your adapter builds a runnable pipeline from `spec` (the active incumbent's node
 
 A **generic LangGraph adapter** ships in `archforge/host/adapters/langgraph.py` and drives a real `graph.stream(...)` — "describe, don't introspect" (it reads node *names*, the stable surface; it never climbs your graph's internals). It is the easiest path for any LangGraph-based MAS. For other frameworks (CrewAI, AutoGen, raw call loops), subclass `BaseHostAdapter` (`archforge/host/adapters/base.py`) — the kit is factored so adapting *any* MAS is cheap, not bespoke-per-framework.
 
-Run it via the dotted-path seam:
+**`init` scaffolds the adapter for you.** You don't code the wiring from scratch: `archforge-optimizer init` writes a generic, name-neutral `archforge_optimizer/` package (the LangGraph adapter skeleton above) into your project root. Edit the `# EDIT:` markers in `archforge_optimizer/app.py` to describe your MAS — the node roster (`_NODES`), edges (`_EDGES`), knob to state map, and the `summarize`/`apply_llm_config`/`reset_llm_config` hooks — then `archforge-optimizer make-spec` builds + lints `archforge_optimizer/spec.json` from it. Once scaffolded, `evolve` auto-defaults to the scaffold: `--adapter archforge_optimizer.host:AppAdapter` and `--seed archforge_optimizer/spec.json` (only pass the flags for a custom adapter/seed). Per-file clobber guards mean re-running `init` never overwrites your edits unless `--force`, and a missing/half-edited adapter is repaired even when `archforge.py` already exists.
+
+Run it via the dotted-path seam — the scaffolded package uses the same `module:Class` form:
 
 ```bash
-archforge-optimizer evolve-loop --adapter your_pkg.your_host:YourAdapter --seed your_spec.json
+archforge-optimizer evolve-loop  # defaults: --adapter archforge_optimizer.host:AppAdapter --seed archforge_optimizer/spec.json
 ```
 
 ---
@@ -286,7 +305,8 @@ archforge-optimizer evolve-loop --adapter your_pkg.your_host:YourAdapter --seed
 ```
 archforge-optimizer <command> [flags]
 
-  init          scaffold .archforge/archforge.py + .env.example + suite.json for this project
+  init          scaffold .archforge/archforge.py + suite.json + the archforge_optimizer/ adapter package
+  make-spec     build + lint archforge_optimizer/spec.json from the EDITED adapter (writes only if it passes)
   lint <path>   run the Spec Linter on a JSON Spec file
   evolve        run one Propose-Evaluate-Commit cycle from the active incumbent
   evolve-loop   repeat evolve until the budget cap or a plateau
@@ -301,8 +321,8 @@ archforge-optimizer <command> [flags]
 | Flag | Purpose |
 |---|---|
 | `--root <dir>` | project root holding `.archforge/` (default `.`) |
-| `--seed <path>` | bootstrap the root incumbent from a Spec JSON (first run) |
-| `--adapter <dotted.path[:Class]>` | your `HostMAS` adapter |
+| `--seed <path>` | bootstrap the root incumbent from a Spec JSON (first run); defaults to `archforge_optimizer/spec.json` when present |
+| `--adapter <dotted.path[:Class]>` | your `HostMAS` adapter; defaults to `archforge_optimizer.host:AppAdapter` when the scaffold is present (not on the `--provider scripted` fake path) |
 | `--provider {scripted\|anthropic\|openai\|groq\|gemini}` | LLM backing the Architect + Judge |
 | `--suite <path>` | evaluation suite JSON (default: `.archforge/suite.json`) |
 | `--tau <float>` | promotion margin τ |
@@ -368,7 +388,7 @@ archforge/
   diff.py             spec_diff / format_diff (human-readable mutation deltas)
   runlog.py           per-cycle run log (cards)
   models.py          Spec/Node/Edge/Step/Trace/RunScore/Attempt/Change/...
-  config.py .py / userconfig.py / config_init.py   versioning + tunable resolver + `init`
+  config.py / userconfig.py / config_init.py   versioning + tunable resolver + `init`
 ```
 
 ---
@@ -392,8 +412,6 @@ The public model surface (`archforge.models`) is the stable contract: `Spec`, `N
 - Provider SDKs (optional, install only what you run): `anthropic`, `openai`, `groq`, `google-genai`
 - For rich tracing (optional): `opentelemetry-sdk` + the per-SDK instrumentors you call
 
-> **Installing from source (development).** For an editable install, `pip install -e .` from a clone of this repository. A flat `pip install .` makes a *non-editable* copy in site-packages, so any later source edit won't take effect at the CLI — if a repo edit ever seems to no-op, check `python -c "import archforge; print(archforge.__file__)"` resolves to the repo, not site-packages.
-
 ---
 
 ## Roadmap
@@ -417,4 +435,6 @@ ArchForge is released under the **MIT License** — see [`LICENSE`](LICENSE) for
 
 ---
 
+<p align="center">
 *ArchForge never patches live state — it swaps which versioned pipeline the host uses.*
+</p>

{archforge_optimizer-0.1.0 → archforge_optimizer-0.2.0}/README.md

@@ -1,9 +1,18 @@
 # ArchForge
 
+<p align="center">
+  <img src="images/logo.png" width="160">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white">
+  <img src="https://img.shields.io/badge/License-MIT-green.svg">
+</p>
+
 > A self-improving meta-layer over multi-agent systems.
 > Point it at your graph, give it a rubric, and it evolves your pipeline — one proven change per cycle.
 
-**Python ≥ 3.11** · **zero hard deps beyond pydantic** · **MIT-licensed** · install from PyPI with `pip install archforge-optimizer` · exercised end-to-end on a real LangGraph MAS (groq + google-genai + chroma, OpenTelemetry-traced).
+**Minimal core dependencies · optional provider and tracing integrations** · install from PyPI with `pip install archforge-optimizer` · exercised end-to-end on a real LangGraph MAS (groq + google-genai + chroma, OpenTelemetry-traced).
 
 ArchForge sits **on top** of an existing multi-agent system (MAS) and improves it run-over-run. Each cycle it inspects where the judge docked points, proposes **one** targeted change — rewriting an agent's prompt, tuning a knob, adding a verifier, re-wiring a node, swapping a model — and keeps it only if it measurably beats the incumbent on a held-out suite. The host MAS keeps running tasks as normal; ArchForge observes the runs and feeds back an improved pipeline.
 
@@ -89,8 +98,8 @@ with tempfile.TemporaryDirectory() as d:
 ```
 
 ```
-$ archforge-optimizer init       # once — scaffolds the project config the Engine reads
-$ python evolve_demo.py
+archforge-optimizer init       # once — scaffolds project config + the archforge_optimizer/ adapter package
+python evolve_demo.py
 action=AUTO_PROMOTE  margin=+0.15
 incumbent_mean=0.55  candidate_mean=0.70
 active_spec_id=57396a49  promoted=True
@@ -164,25 +173,29 @@ pip install archforge-optimizer
 # Optional: install the provider SDK(s) you actually run (none required to import)
 pip install "archforge-optimizer[providers-groq,providers-gemini]"
 
-# 2. Scaffold per-project config — writes .archforge/archforge.py (tunables),
-#    .archforge/suite.json (the eval tasks), .env.example (key template)
+# 2. Scaffold per-project config + the adapter package — writes:
+#      .archforge/archforge.py        (tunables — ACTIVE sane defaults)
+#      .archforge/suite.json          (the eval tasks you optimize against)
+#      archforge_optimizer/           (a generic LangGraph adapter skeleton — 5 files)
+#        __init__.py  host.py  app.py  sidecar.py  test_smoke_offline.py
 archforge-optimizer init
 
-# 3. Put your API keys in .env (gitignored)  ── e.g. GROQ_API_KEY=..., GEMINI_API_KEY=...
+# 3. Put your provider API key in a root `.env` (gitignored)  ── e.g. GEMINI_API_KEY=...
+#    (init never writes or touches .env — it just tells you to put the key there.)
 
-# 4. Lint a Spec before running it — checks DAG validity, node refs, type rules
-archforge-optimizer lint path/to/spec.json
+# 4. Edit your MAS details into archforge_optimizer/app.py — fill every `# EDIT:` marker
+#    (the node roster, edges, knobs, summarize/apply_llm_config hooks). Then build the
+#    bootstrap Spec from your EDITED adapter: it lints the roster first and writes
+#    archforge_optimizer/spec.json only if valid (rc=1 + the faults if not — fix + rerun).
+archforge-optimizer make-spec     # → archforge_optimizer/spec.json (lint OK)
 
-# 5. Run one Propose-Evaluate-Commit cycle against your MAS, wired by an adapter
-archforge-optimizer evolve \
-    --adapter your_pkg.your_host:YourAdapter \
-    --seed your_spec.json
+# 5. Run one Propose-Evaluate-Commit cycle against your MAS. evolve auto-defaults
+#    --adapter archforge_optimizer.host:AppAdapter and --seed archforge_optimizer/spec.json
+archforge-optimizer evolve
 
 # 6. Run the full loop: repeat evolve until K consecutive non-promotions (plateau)
-#    or a cycle/budget cap is hit
-archforge-optimizer evolve-loop \
-    --adapter your_pkg.your_host:YourAdapter \
-    --seed your_spec.json --max-cycles 50
+# or set flags in archforge.py
+archforge-optimizer evolve-loop --max-cycles 50
 
 # 7. Inspect
 archforge-optimizer status     # print the active incumbent Spec id, lineage, counts
@@ -190,11 +203,15 @@ archforge-optimizer report     # print per-attempt score deltas (incumbent vs ca
 archforge-optimizer approve --all   # move PENDING_HUMAN structural wins into active
 ```
 
+> `init` never writes `.env.example` or `spec.json` — the provider key lives in your root
+> `.env` (gitignored), and `spec.json` comes from `make-spec` (your real roster, linted),
+> not a template. Lint any Spec by hand with `archforge-optimizer lint path/to/spec.json`.
+
 > You can also invoke as `python -m archforge ...` — identical surface.
 >
 > **From source (development).** Clone the repo and `pip install -e .` for an editable install.
 
-The `--provider` flag selects the LLM backing the Architect + Judge (`scripted` by default for zero-cost runs; `anthropic` / `openai` / `groq` / `gemini` for real runs). The host MAS is wired via `--adapter my_pkg.my_host:MyAdapter`.
+The `--provider` flag selects the LLM backing the Architect + Judge (`anthropic` / `openai` / `groq` / `gemini` for real runs). The host MAS is wired via `--adapter my_pkg.my_host:MyAdapter` — and after `init`, `evolve` already defaults it to the `archforge_optimizer.host:AppAdapter`, so you only pass the flag for a custom adapter.
 
 ---
 
@@ -243,10 +260,12 @@ Your adapter builds a runnable pipeline from `spec` (the active incumbent's node
 
 A **generic LangGraph adapter** ships in `archforge/host/adapters/langgraph.py` and drives a real `graph.stream(...)` — "describe, don't introspect" (it reads node *names*, the stable surface; it never climbs your graph's internals). It is the easiest path for any LangGraph-based MAS. For other frameworks (CrewAI, AutoGen, raw call loops), subclass `BaseHostAdapter` (`archforge/host/adapters/base.py`) — the kit is factored so adapting *any* MAS is cheap, not bespoke-per-framework.
 
-Run it via the dotted-path seam:
+**`init` scaffolds the adapter for you.** You don't code the wiring from scratch: `archforge-optimizer init` writes a generic, name-neutral `archforge_optimizer/` package (the LangGraph adapter skeleton above) into your project root. Edit the `# EDIT:` markers in `archforge_optimizer/app.py` to describe your MAS — the node roster (`_NODES`), edges (`_EDGES`), knob to state map, and the `summarize`/`apply_llm_config`/`reset_llm_config` hooks — then `archforge-optimizer make-spec` builds + lints `archforge_optimizer/spec.json` from it. Once scaffolded, `evolve` auto-defaults to the scaffold: `--adapter archforge_optimizer.host:AppAdapter` and `--seed archforge_optimizer/spec.json` (only pass the flags for a custom adapter/seed). Per-file clobber guards mean re-running `init` never overwrites your edits unless `--force`, and a missing/half-edited adapter is repaired even when `archforge.py` already exists.
+
+Run it via the dotted-path seam — the scaffolded package uses the same `module:Class` form:
 
 ```bash
-archforge-optimizer evolve-loop --adapter your_pkg.your_host:YourAdapter --seed your_spec.json
+archforge-optimizer evolve-loop  # defaults: --adapter archforge_optimizer.host:AppAdapter --seed archforge_optimizer/spec.json
 ```
 
 ---
@@ -256,7 +275,8 @@ archforge-optimizer evolve-loop --adapter your_pkg.your_host:YourAdapter --seed
 ```
 archforge-optimizer <command> [flags]
 
-  init          scaffold .archforge/archforge.py + .env.example + suite.json for this project
+  init          scaffold .archforge/archforge.py + suite.json + the archforge_optimizer/ adapter package
+  make-spec     build + lint archforge_optimizer/spec.json from the EDITED adapter (writes only if it passes)
   lint <path>   run the Spec Linter on a JSON Spec file
   evolve        run one Propose-Evaluate-Commit cycle from the active incumbent
   evolve-loop   repeat evolve until the budget cap or a plateau
@@ -271,8 +291,8 @@ archforge-optimizer <command> [flags]
 | Flag | Purpose |
 |---|---|
 | `--root <dir>` | project root holding `.archforge/` (default `.`) |
-| `--seed <path>` | bootstrap the root incumbent from a Spec JSON (first run) |
-| `--adapter <dotted.path[:Class]>` | your `HostMAS` adapter |
+| `--seed <path>` | bootstrap the root incumbent from a Spec JSON (first run); defaults to `archforge_optimizer/spec.json` when present |
+| `--adapter <dotted.path[:Class]>` | your `HostMAS` adapter; defaults to `archforge_optimizer.host:AppAdapter` when the scaffold is present (not on the `--provider scripted` fake path) |
 | `--provider {scripted\|anthropic\|openai\|groq\|gemini}` | LLM backing the Architect + Judge |
 | `--suite <path>` | evaluation suite JSON (default: `.archforge/suite.json`) |
 | `--tau <float>` | promotion margin τ |
@@ -338,7 +358,7 @@ archforge/
   diff.py             spec_diff / format_diff (human-readable mutation deltas)
   runlog.py           per-cycle run log (cards)
   models.py          Spec/Node/Edge/Step/Trace/RunScore/Attempt/Change/...
-  config.py .py / userconfig.py / config_init.py   versioning + tunable resolver + `init`
+  config.py / userconfig.py / config_init.py   versioning + tunable resolver + `init`
 ```
 
 ---
@@ -362,8 +382,6 @@ The public model surface (`archforge.models`) is the stable contract: `Spec`, `N
 - Provider SDKs (optional, install only what you run): `anthropic`, `openai`, `groq`, `google-genai`
 - For rich tracing (optional): `opentelemetry-sdk` + the per-SDK instrumentors you call
 
-> **Installing from source (development).** For an editable install, `pip install -e .` from a clone of this repository. A flat `pip install .` makes a *non-editable* copy in site-packages, so any later source edit won't take effect at the CLI — if a repo edit ever seems to no-op, check `python -c "import archforge; print(archforge.__file__)"` resolves to the repo, not site-packages.
-
 ---
 
 ## Roadmap
@@ -387,4 +405,6 @@ ArchForge is released under the **MIT License** — see [`LICENSE`](LICENSE) for
 
 ---
 
+<p align="center">
 *ArchForge never patches live state — it swaps which versioned pipeline the host uses.*
+</p>

{archforge_optimizer-0.1.0 → archforge_optimizer-0.2.0}/archforge/cli.py

@@ -53,7 +53,9 @@ from archforge.lint import lint
 from archforge.runlog import RunLog
 from archforge.stores import AttemptStore, SpecStore, TraceStore
 from archforge.suite import Suite, load_suite_file
-from archforge.config_init import archforge_config_text, env_example_text, _DEFAULT_SUITE_JSON
+from archforge.config_init import (
+    archforge_config_text, _DEFAULT_SUITE_JSON, adapter_package_files,
+)
 
 # System config (provider roster, CLI fixtures, PROG, .env loader) — single source
 # in archforge.config. The TUNABLE defaults (tau/delta/repeats/provider/models/…)
@@ -230,12 +232,23 @@ def _build_parser() -> argparse.ArgumentParser:
     _add_store_args(lint_p)
     lint_p.add_argument("path", help="path to a Spec JSON file")
 
-    # --- init (scaffold user config) -----------------------------------------
+    # --- init (scaffold user config + generic adapter package) ----------------
     init_p = sub.add_parser("init",
-                            help="scaffold .archforge/archforge.py + .env.example for this project")
+                            help="scaffold .archforge/archforge.py + the archforge_optimizer/ adapter package")
     _add_store_args(init_p)   # --root selects where archforge.py is written
     init_p.add_argument("--force", action="store_true",
-                        help="overwrite an existing .archforge/archforge.py")
+                        help="overwrite an existing .archforge/archforge.py + adapter package")
+
+    # --- make-spec (build spec.json from the edited adapter) ------------------
+    mk = sub.add_parser("make-spec",
+                        help="build + lint archforge_optimizer/spec.json from the edited adapter app")
+    _add_store_args(mk)
+    mk.add_argument("--adapter", metavar="DOTTED.PATH[:Class]",
+                    default="archforge_optimizer.host:AppAdapter",
+                    help="adapter module:Class whose app.build_spec() builds the Spec "
+                         "(default: archforge_optimizer.host:AppAdapter)")
+    mk.add_argument("--out", metavar="PATH", default="archforge_optimizer/spec.json",
+                    help="where to write the Spec JSON (default: archforge_optimizer/spec.json)")
 
     return parser
 
@@ -519,6 +532,23 @@ def _install_resource_warning_quieteners() -> None:
 _install_resource_warning_quieteners()
 
 
+# The scaffolded adapter package (`archforge-optimizer init`) + its make-spec output.
+# `evolve` defaults to these when present (no `--adapter`/`--seed` flag needed); the
+# flags stay for custom adapters / arbitrary seed paths.
+_SCAFFOLD_ADAPTER = "archforge_optimizer.host:AppAdapter"
+_SCAFFOLD_SPEC = "archforge_optimizer/spec.json"
+
+
+def _scaffolded_adapter_available() -> bool:
+    """True when `init` wrote the adapter package at cwd (its host.py exists)."""
+    return (Path.cwd() / "archforge_optimizer" / "host.py").is_file()
+
+
+def _scaffolded_spec_available() -> bool:
+    """True when `make-spec` produced archforge_optimizer/spec.json at cwd."""
+    return (Path.cwd() / "archforge_optimizer" / "spec.json").is_file()
+
+
 def _cmd_evolve(args: argparse.Namespace, *, components: Components | None,
                 loop: bool) -> int:
     # Injected `components` (the test/embedding path) always win — they ARE the
@@ -527,6 +557,7 @@ def _cmd_evolve(args: argparse.Namespace, *, components: Components | None,
     # works" contract): a project with no .archforge/archforge.py gets the init hint
     # and rc 1 instead of a bogus run. No-op under the pytest gate (tests use the
     # in-memory sane template).
+    components_injected = components is not None
     if components is None:
         try:
             ucfg.ensure_initialized()
@@ -544,6 +575,11 @@ def _cmd_evolve(args: argparse.Namespace, *, components: Components | None,
 
     specs, atts, traces = _stores(args.root)
 
+    # Default `--seed` to the scaffolded spec.json when the user scaffolded +
+    # ran `make-spec` (no flag needed); the flag still overrides for custom seeds.
+    if getattr(args, "seed", None) is None and _scaffolded_spec_available():
+        args.seed = _SCAFFOLD_SPEC
+
     # zero-LLM bootstrap of the root incumbent from --seed (if none active)
     active = _ensure_incumbent(args, specs)
     if active is None:
@@ -556,7 +592,15 @@ def _cmd_evolve(args: argparse.Namespace, *, components: Components | None,
     # --adapter: swap the runtime host for an external MAS adapter (a HostMAS /
     # BaseHostAdapter) while keeping the --provider organs (Architect/Judge).
     # This is the "adapt any MAS" seam: point at an adapter class, no core edit.
+    # When the user scaffolded the adapter package (`init`), DEFAULT --adapter to
+    # its AppAdapter (no flag needed); the flag still overrides for custom adapters.
+    # Skipped on the scripted fake path (FakeHostMAS is the zero-cost host) and
+    # when `components` were injected (test/embedding path owns the host).
     adapter_path = getattr(args, "adapter", None)
+    if (adapter_path is None and not components_injected
+            and _scaffolded_adapter_available()
+            and (args.provider or ucfg.get("PROVIDER")) != "scripted"):
+        adapter_path = _SCAFFOLD_ADAPTER
     if adapter_path:
         organs = Components(host=_import_adapter(adapter_path), judge=organs.judge,
                             architect=organs.architect, suite=organs.suite)
@@ -788,13 +832,48 @@ def _cmd_lint(path: str) -> int:
 
 
 def _cmd_init(args: argparse.Namespace) -> int:
-    """Scaffold `.archforge/archforge.py` (user-editable config) + `.env.example`
-    (repo root). Never touches a real `.env`. Refuses to clobber an existing
-    `archforge.py` unless `--force`; never overwrites an existing `.env.example`."""
+    """Scaffold the ArchForge project:
+
+      - ``archforge_optimizer/`` — a generic, name-neutral LangGraph adapter skeleton
+        at the project root (cwd) whose ``# EDIT:`` markers the user fills for their MAS.
+      - ``.archforge/archforge.py`` — user-editable ACTIVE config (sane defaults).
+      - ``.archforge/suite.json`` — one-task eval sidecar (the user tunes the tasks).
+
+    Does NOT write ``.env.example`` or ``spec.json``. The user's provider API key goes
+    in the repo-root ``.env`` (gitignored); the bootstrap Spec is generated by the
+    separate ``make-spec`` command from the EDITED adapter (not a placeholder template).
+    Never touches a real ``.env``; nothing is echoed. Refuses to clobber an existing
+    ``archforge.py`` unless ``--force``; never overwrites ``suite.json``; repairs the
+    adapter per-file (only fills missing files unless ``--force``).
+
+    The adapter scaffold runs FIRST so a re-run with an existing ``archforge.py`` can
+    still restore/repair a missing or half-edited ``archforge_optimizer/`` without
+    ``--force`` — the per-file keep/``--force`` guards are independent of ``.archforge/``.
+    The ``archforge.py`` refuse-clobber then fires its rc=2 only AFTER the adapter is
+    already in place, preserving the existing contract."""
     root = Path(args.root or _DEFAULT_ROOT)
     cfg_path = root / "archforge.py"
+    pkg_dir = Path.cwd() / "archforge_optimizer"
+
+    # 1. archforge_optimizer/ — the generic LangGraph adapter skeleton, scaffolded at
+    # the project root (cwd) so `--adapter archforge_optimizer.host:AppAdapter` resolves
+    # (main() puts cwd on sys.path). The user EDITS their MAS details (the # EDIT:
+    # markers in app.py) instead of coding the wiring from scratch. Per-file clobber
+    # guard mirroring suite.json: never overwrite an existing file unless --force, so a
+    # half-edited scaffold still gets its missing files filled. Runs FIRST (independent
+    # of .archforge/) so a re-run can repair a deleted adapter without --force.
+    for relpath, content in adapter_package_files().items():
+        fpath = pkg_dir / relpath
+        if fpath.exists() and not args.force:
+            print(f"kept:    archforge_optimizer/{relpath}  (already present)")
+            continue
+        fpath.parent.mkdir(parents=True, exist_ok=True)
+        fpath.write_text(content, encoding="utf-8")
+        print(f"created: archforge_optimizer/{relpath}")
 
-    # 1. archforge.py — refuse-clobber unless --force.
+    # 2. archforge.py — refuse-clobber unless --force. (rc=2 if exists, not --force.)
+    # Runs AFTER the adapter scaffold so a re-run that only needs to repair
+    # archforge_optimizer/ still gets it even when archforge.py is already present.
     if cfg_path.exists() and not args.force:
         print(f"! {cfg_path} already exists. Re-run with --force to overwrite "
               "(your edits would be lost).", file=sys.stderr)
@@ -803,14 +882,6 @@ def _cmd_init(args: argparse.Namespace) -> int:
     cfg_path.write_text(archforge_config_text(), encoding="utf-8")
     print(f"created: {cfg_path}  (edit a value to change a default; the file is ACTIVE as-is)")
 
-    # 2. .env.example — create once at the repo root (cwd), never overwrite.
-    env_example = Path(".env.example")
-    if env_example.exists():
-        print(f"kept:    {env_example}  (already present)")
-    else:
-        env_example.write_text(env_example_text(), encoding="utf-8")
-        print(f"created: {env_example}")
-
     # 3. suite.json — seed the eval-task sidecar next to archforge.py (so --root
     # relocations also move the seeded suite); never overwrite — the user may have
     # tuned the tasks. Byte-identical to the CLI's one-task fallback fixture.
@@ -820,10 +891,118 @@ def _cmd_init(args: argparse.Namespace) -> int:
     else:
         suite_path.write_text(_DEFAULT_SUITE_JSON, encoding="utf-8")
         print(f"created: {suite_path}  (edit the tasks to change what you optimize against)")
-    print(f"\nNext: edit {cfg_path}, then run `{PROG} evolve --seed <spec.json>`.")
+
+    spec_path = pkg_dir / "spec.json"
+    print(f"\nNext: put your provider API key in a root `.env` (gitignored), edit the "
+          f"# EDIT: markers in {pkg_dir / 'app.py'} (your MAS's node roster/edges/knobs), "
+          f"run `{PROG} make-spec` to build + lint `archforge_optimizer/spec.json` from "
+          f"your edited adapter, then `{PROG} evolve --adapter "
+          f"archforge_optimizer.host:AppAdapter --seed {spec_path}`.")
+    return 0
+
+
+def _cmd_make_spec(args: argparse.Namespace) -> int:
+    """Build + lint + write the bootstrap Spec JSON from the EDITED adapter.
+
+    Unlike `init` (which scaffolds a placeholder), this reads the user's actual MAS
+    details: it imports ``--adapter``, lets its app build the bootstrap Spec, runs the
+    Spec Linter on the result, and — only if it passes — writes it to ``--out``
+    (default ``archforge_optimizer/spec.json``). So the spec.json that ``evolve --seed``
+    consumes is the user's real roster, not a template. A failing lint returns rc=1
+    WITHOUT writing (the user fixes the # EDIT: markers and re-runs). cwd is on
+    sys.path (``main()`` puts it there before dispatch), so
+    ``--adapter archforge_optimizer.host:AppAdapter`` resolves.
+
+    The app's ``build_spec()`` itself asserts-not-lint (it surfaces a malformed roster
+    loudly); for ``make-spec`` we want a clean rc=1 + the lint faults, not a raw
+    traceback. So a construction-time ``AssertionError`` is caught and its embedded
+    fault list is re-printed as the lint output."""
+    try:
+        _flush_adapter_cache(args.adapter)          # always read the current cwd's files
+        host = _import_adapter(args.adapter)
+    except AssertionError as exc:
+        print(f"! {args.adapter}: built Spec fails the linter — not writing {args.out}:",
+              file=sys.stderr)
+        for fault in _parse_build_spec_assert(str(exc)):
+            print(f"  {fault}", file=sys.stderr)
+        print("  edit the # EDIT: markers in your adapter app.py and re-run `make-spec`.",
+              file=sys.stderr)
+        return 1
+    # `app_spec()` is the adapter's published bootstrap Spec (LangGraphHostAdapter
+    # builds + caches it in __init__). It is not on the bare HostMAS protocol, so we
+    # surface a clear error for an adapter that lacks it rather than AttributeError.
+    build_spec = getattr(host, "app_spec", None)
+    if build_spec is None:
+        print(f"! {args.adapter} ({type(host).__name__}) exposes no app_spec() — "
+              f"make-spec needs a LangGraph-style adapter that builds a bootstrap Spec. "
+              f"Pass the host class (e.g. archforge_optimizer.host:AppAdapter).",
+              file=sys.stderr)
+        return 1
+    spec = build_spec()
+    faults = lint(spec)
+    if faults:
+        print(f"! {args.adapter}: built Spec fails the linter — not writing {args.out}:",
+              file=sys.stderr)
+        for f in faults:
+            loc = f" [{f.location}]" if f.location else ""
+            print(f"  {f.code}{loc}: {f.message}", file=sys.stderr)
+        print("  edit the # EDIT: markers in your adapter app.py and re-run `make-spec`.",
+              file=sys.stderr)
+        return 1
+    out_path = Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(spec.model_dump_json(indent=2), encoding="utf-8")
+    print(f"created: {out_path}  (lint OK; run `{PROG} evolve --adapter "
+          f"{args.adapter} --seed {out_path}`)")
     return 0
 
 
+def _parse_build_spec_assert(message: str) -> list[str]:
+    """Extract the per-fault strings from a ``build_spec()`` AssertionError message
+    (``LangGraph app Spec failed lint: ["code@loc: msg", ...]``). Falls back to the raw
+    tail of the message if the embedded list repr can't be parsed — never raises, so
+    ``make-spec``'s error path stays crash-free on a malformed assert."""
+    import ast
+    marker = "failed lint:"
+    idx = message.find(marker)
+    if idx < 0:
+        return [message.strip()]
+    tail = message[idx + len(marker):].strip()
+    try:
+        parsed = ast.literal_eval(tail)
+        if isinstance(parsed, (list, tuple)) and all(isinstance(x, str) for x in parsed):
+            return list(parsed)
+    except (ValueError, SyntaxError):
+        pass
+    return [tail]
+
+
+def _flush_adapter_cache(dotted: str) -> None:
+    """Drop a ``module:Class`` adapter's module subtree from ``sys.modules`` so the NEXT
+    import reads the *current cwd's* files, not a module cached from an earlier cwd.
+
+    Single-process reuse (the real CLI runs one command per process, so this is a no-op
+    there) defeats ``make-spec``/``evolve`` when the user edits ``app.py`` and re-runs
+    in the SAME process (e.g. the test harness, or a long-lived embedding): the stale
+    ``archforge_optimizer`` — bound to a previous tmp cwd's files — would shadow the
+    edit. Flushing + ``importlib.invalidate_caches()`` makes \"build from the edited
+    adapter\" honest. Scoped to the adapter's own top-level package so core imports are
+    untouched."""
+    if ":" in dotted:
+        modpath = dotted.split(":", 1)[0]
+    else:
+        modpath = dotted
+    top = modpath.split(".", 1)[0]
+    stale = [name for name in list(sys.modules) if name == top or name.startswith(top + ".")]
+    for name in stale:
+        sys.modules.pop(name, None)
+    importlib.invalidate_caches()
+
+
+
+
+
+
 # --------------------------------------------------------------------------- #
 # entry
 # --------------------------------------------------------------------------- #
@@ -869,6 +1048,8 @@ def main(argv: list[str] | None = None, *,
         return _cmd_reject(args)
     if args.command == "init":
         return _cmd_init(args)
+    if args.command == "make-spec":
+        return _cmd_make_spec(args)
     if args.command == "evolve":
         return _cmd_evolve(args, components=components, loop=False)
     if args.command == "evolve-loop":

{archforge_optimizer-0.1.0 → archforge_optimizer-0.2.0}/archforge/config.py

@@ -29,7 +29,7 @@ from pathlib import Path
 # =========================================================================== #
 # The package version. Read by hatchling for the built distribution and
 # re-exported as `archforge.__version__` (archforge/__init__.py). One place.
-VERSION: str = "0.1.0"
+VERSION: str = "0.2.0"
 
 
 # =========================================================================== #