atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a3_og_features/forge_loop.py

@@ -0,0 +1,528 @@
+"""Tier a3 — the LLM ↔ Forge iteration loop.
+
+This is the headline pipeline: intent → LLM emits code → Forge enforces
+tier law → structured feedback → LLM iterates → … → certify ≥ threshold.
+
+Forge is the architecture substrate.  An LLM (any provider) is the
+generator.  Together they produce **architecturally-coherent** code in a
+controlled loop where the LLM is held accountable to a strict layered
+discipline.
+
+Public API:
+    run_iterate(intent, *, output, package, llm, ...) -> IterateReport
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from pathlib import Path
+from typing import Any
+
+from ..a0_qk_constants.gen_language import (
+    ALLOWED_FILE_EXTS,
+    EMITS_INIT_FILES,
+    EMITS_PYPROJECT,
+    Language,
+    normalize_language,
+    pkg_root_for,
+)
+from ..a0_qk_constants.tier_names import TIER_NAMES
+from ..a1_at_functions.certify_checks import certify
+from ..a1_at_functions.compiler_feedback import (
+    pack_compile_feedback,
+    should_fix_round,
+)
+from ..a1_at_functions.forge_feedback import (
+    compute_reuse_stats,
+    pack_feedback,
+    pack_initial_intent,
+    parse_files_from_response,
+    system_prompt,
+)
+from ..a1_at_functions.generation_quality import (
+    apply_docs_phase,
+    apply_docstring_phase,
+    apply_test_phase,
+)
+from ..a1_at_functions.import_smoke import import_smoke
+from ..a1_at_functions.llm_client import LLMClient, resolve_default_client
+from ..a1_at_functions.scaffold_js import render_js_readme, render_package_json
+from ..a1_at_functions.scaffold_pyproject import render_pyproject
+from ..a1_at_functions.scaffold_starter import (
+    render_gitignore,
+    render_readme,
+    render_tests_conftest,
+    render_tests_init,
+)
+from ..a1_at_functions.scout_walk import harvest_repo
+from ..a1_at_functions.tier_init_rebuild import rebuild_tier_inits
+from ..a1_at_functions.transcript_log import TranscriptLog
+from ..a1_at_functions.wire_check import scan_violations
+from ..a2_mo_composites.manifest_store import ManifestStore
+
+try:
+    from .emergent_pipeline_integration import emergent_overlay_for_path
+    _HAS_EMERGENT = True
+except Exception:  # noqa: BLE001
+    _HAS_EMERGENT = False
+
+
+def _scaffold_package(output: Path, package: str, *,
+                      intent: str = "",
+                      language: Language = "python") -> Path:
+    """Scaffold the surrounding package skeleton for the LLM to fill in.
+
+    For Python, this is a complete pip-installable layout: 5 tier
+    directories with ``__init__.py``s, a real ``pyproject.toml`` rooted
+    at ``output/``, ``README.md``, ``.gitignore``, and ``tests/`` with a
+    conftest that adds ``src/`` to ``sys.path``.  After this runs,
+    ``pip install -e <output>`` works.
+
+    For JavaScript / TypeScript, the layout is simpler: 5 tier
+    directories at ``output/<package>/`` (no ``src/`` wrapper), a
+    minimal ``package.json`` with ``"type": "module"``, and a README.
+    No ``__init__.py`` (ES modules don't need one), no test framework
+    config (Forge doesn't currently run JS tests in certify).
+    """
+    pkg_root = output / pkg_root_for(language, package)
+    for tier in TIER_NAMES:
+        d = pkg_root / tier
+        d.mkdir(parents=True, exist_ok=True)
+        if EMITS_INIT_FILES[language]:
+            (d / "__init__.py").write_text(
+                f'"""{tier}."""\n', encoding="utf-8"
+            )
+    if EMITS_INIT_FILES[language]:
+        (pkg_root / "__init__.py").write_text(
+            f'"""{package} — generated by atomadic-forge iterate."""\n'
+            f'__version__ = "0.0.1"\n',
+            encoding="utf-8",
+        )
+
+    # Top-level scaffolds — only write if absent so re-runs don't clobber
+    # an LLM-improved README.
+    if EMITS_PYPROJECT[language]:
+        pyproject = output / "pyproject.toml"
+        if not pyproject.exists():
+            pyproject.write_text(
+                render_pyproject(
+                    package=package,
+                    description=(intent or "")[:120].strip() or f"{package} package",
+                    console_script_target="a4_sy_orchestration.cli:main",
+                ),
+                encoding="utf-8",
+            )
+    else:
+        # JS/TS: minimal package.json with type: module so ES6 imports resolve.
+        pj = output / "package.json"
+        if not pj.exists():
+            pj.write_text(
+                render_package_json(
+                    package=package,
+                    description=(intent or "")[:120].strip(),
+                    language=language,
+                ),
+                encoding="utf-8",
+            )
+
+    readme = output / "README.md"
+    if not readme.exists():
+        if language == "python":
+            readme.write_text(
+                render_readme(package=package, intent=intent or "(unspecified)"),
+                encoding="utf-8",
+            )
+        else:
+            readme.write_text(
+                render_js_readme(package=package,
+                                  intent=intent or "(unspecified)",
+                                  language=language),
+                encoding="utf-8",
+            )
+    gi = output / ".gitignore"
+    if not gi.exists():
+        gi.write_text(render_gitignore(), encoding="utf-8")
+
+    # Python-only test scaffolding.  JS/TS test runners (vitest/jest/node:test)
+    # don't need a conftest.py; that's a 0.3 roadmap item.
+    if language == "python":
+        tests_dir = output / "tests"
+        tests_dir.mkdir(exist_ok=True)
+        init = tests_dir / "__init__.py"
+        if not init.exists():
+            init.write_text(render_tests_init(), encoding="utf-8")
+        cf = tests_dir / "conftest.py"
+        if not cf.exists():
+            cf.write_text(render_tests_conftest(package=package), encoding="utf-8")
+
+    return pkg_root
+
+
+_PATH_REJECT_CHARS = ("<", ">", "|", "*", "?", '"', "\x00")
+
+
+def _safe_path(rel: str, language: Language = "python") -> bool:
+    """Reject placeholder/metachar/traversal paths the LLM may have emitted.
+
+    Small models often echo template tokens like ``<pkg>`` or ``${name}``
+    verbatim instead of substituting.  We refuse those instead of crashing
+    on Windows or writing garbage files.
+
+    File-suffix allow-list is language-aware: a Python evolve refuses
+    LLM-emitted ``.js`` files (and vice-versa) so the output tree stays
+    monolingual.  ``.md`` is allowed in every language.
+    """
+    rel = rel.strip()
+    if not rel:
+        return False
+    if any(ch in rel for ch in _PATH_REJECT_CHARS):
+        return False
+    if ".." in rel.replace("\\", "/").split("/"):
+        return False
+    rel_lower = rel.lower()
+    allowed = ALLOWED_FILE_EXTS[language]
+    if not any(rel_lower.endswith(ext) for ext in allowed):
+        return False
+    return True
+
+
+def _write_files(output: Path, files: list[dict[str, str]],
+                  language: Language = "python") -> list[str]:
+    written: list[str] = []
+    output_resolved = output.resolve()
+    for f in files:
+        rel = f.get("path", "").lstrip("/\\")
+        if not _safe_path(rel, language=language):
+            continue
+        try:
+            target = (output / rel).resolve()
+            target.relative_to(output_resolved)  # prompt-injection / traversal guard
+        except (ValueError, OSError):
+            continue
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(f.get("content", ""), encoding="utf-8")
+        except OSError:
+            continue
+        written.append(str(target.relative_to(output_resolved).as_posix()))
+    return written
+
+
+def _run_fix_rounds(
+    *,
+    pkg_root: Path,
+    output: Path,
+    package: str,
+    language: Language,
+    llm: LLMClient,
+    sys_prompt: str,
+    max_fix_rounds: int,
+    transcript: TranscriptLog | None,
+    turn: int,
+) -> list[dict[str, Any]]:
+    """Run up to ``max_fix_rounds`` import-smoke fix rounds.
+
+    Each round:
+      1. Run import_smoke against the just-written package.
+      2. If importable → return what we did so far; the regular turn
+         continues.
+      3. Otherwise pack a fix-round prompt with the error trace and
+         re-call the LLM, write the response files, and loop.
+
+    Lane A W3 contract — the fix-round NEVER scores quality; it only
+    asks for the minimum patch to make the package import. This keeps
+    the regular --max-iterations budget for actual quality work.
+    """
+    rounds: list[dict[str, Any]] = []
+    if max_fix_rounds < 1 or language != "python":
+        # Smoke is Python-only; JS/TS skip fix rounds today.
+        return rounds
+    for attempt in range(1, max_fix_rounds + 1):
+        smoke = import_smoke(output_root=output, package=package)
+        if smoke.get("importable"):
+            return rounds
+        if not should_fix_round(smoke):
+            return rounds
+        prompt = pack_compile_feedback(
+            smoke, package=package,
+            fix_round_index=attempt,
+            max_fix_rounds=max_fix_rounds,
+        )
+        if transcript:
+            transcript.append(
+                "prompt", prompt, role="user", llm=llm.name,
+                extra={"turn": turn, "phase": "fix-round",
+                       "fix_round": attempt},
+            )
+        response = llm.call(prompt, system=sys_prompt)
+        if transcript:
+            transcript.append(
+                "response", response, role="assistant", llm=llm.name,
+                extra={"turn": turn, "phase": "fix-round",
+                       "fix_round": attempt},
+            )
+        files = parse_files_from_response(response)
+        # The contract said: emit `[]` to signal 'env error, give up'.
+        if not files and response.strip().endswith("[]"):
+            rounds.append({
+                "fix_round": attempt,
+                "files_written": [],
+                "halted_reason": "llm_signaled_environment_error",
+                "smoke_error_kind": smoke.get("error_kind"),
+            })
+            return rounds
+        written = _write_files(output, files, language=language)
+        if pkg_root.exists() and EMITS_INIT_FILES[language]:
+            rebuild_tier_inits(pkg_root)
+        rounds.append({
+            "fix_round": attempt,
+            "files_written": written,
+            "smoke_error_kind": smoke.get("error_kind"),
+            "smoke_error_message": smoke.get("error_message"),
+        })
+    return rounds
+
+
+def run_iterate(
+    intent: str,
+    *,
+    output: Path,
+    package: str = "generated",
+    seed_repo: Path | list[Path] | None = None,
+    llm: LLMClient | None = None,
+    max_iterations: int = 5,
+    max_fix_rounds: int = 0,
+    target_score: float = 75.0,
+    apply: bool = True,
+    language: Language | str = "python",
+) -> dict[str, Any]:
+    """Run the LLM ↔ Forge loop.
+
+    Termination: certify ≥ ``target_score`` AND wire PASS, OR ``max_iterations``
+    exhausted, OR LLM emits an empty file list (signals "done").
+
+    ``apply=False`` returns the planned prompt + initial response without
+    writing files (useful for sanity-checking the prompt shape).
+
+    ``language`` selects the target output language: ``"python"`` (default,
+    pip-installable layout under ``src/<package>/``), ``"javascript"`` or
+    ``"typescript"`` (ES-module layout under ``<package>/``).
+    """
+    output = Path(output).resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    llm = llm or resolve_default_client()
+    lang: Language = normalize_language(language)
+    pkg_root = (_scaffold_package(output, package, intent=intent, language=lang)
+                if apply else output / pkg_root_for(lang, package))
+    transcript = TranscriptLog(output) if apply else None
+
+    # Optional seed catalog from one or more sibling repos.
+    seed_catalog: list[dict] = []
+    seed_repos = ([seed_repo] if isinstance(seed_repo, Path) else
+                  (list(seed_repo) if seed_repo else []))
+    for sr in seed_repos:
+        sr = Path(sr)
+        if sr.exists():
+            scout = harvest_repo(sr)
+            seed_catalog.extend(scout.get("symbols", []))
+
+    turn_log: list[dict[str, Any]] = []
+    history_files: list[str] = []
+    sys_prompt = system_prompt(language=lang)
+
+    # ── Turn 0: initial intent ────────────────────────────────────────────
+    prompt = pack_initial_intent(intent, package=package,
+                                   seed_catalog=seed_catalog, language=lang)
+    if not apply:
+        return {
+            "schema_version": "atomadic-forge.iterate/v1",
+            "applied": False,
+            "package": package,
+            "language": lang,
+            "system_prompt": sys_prompt,
+            "first_prompt": prompt,
+            "llm": llm.name,
+        }
+
+    if transcript:
+        transcript.append("system", sys_prompt, role="system", llm=llm.name)
+        transcript.append("prompt", prompt, role="user", llm=llm.name,
+                          extra={"turn": 0, "phase": "initial"})
+    response = llm.call(prompt, system=sys_prompt)
+    if transcript:
+        transcript.append("response", response, role="assistant",
+                          llm=llm.name, extra={"turn": 0})
+    files = parse_files_from_response(response)
+    parse_retried = False
+    if not files and response.strip() and not response.strip().endswith("[]"):
+        retry_prompt = (
+            "Your previous response did not parse as a JSON array of "
+            "`{path, content}` objects.  Output ONLY the JSON array "
+            "literal, no prose, no markdown fences, no comments.  If you "
+            "need to indicate completion, output the exact two characters "
+            "`[]`.\n\n"
+            "Re-emit your output now."
+        )
+        if transcript:
+            transcript.append("prompt", retry_prompt, role="user",
+                              llm=llm.name,
+                              extra={"turn": 0, "phase": "parse-retry"})
+        response = llm.call(retry_prompt, system=sys_prompt)
+        if transcript:
+            transcript.append("response", response, role="assistant",
+                              llm=llm.name,
+                              extra={"turn": 0, "phase": "parse-retry"})
+        files = parse_files_from_response(response)
+        parse_retried = True
+    written = _write_files(output, files, language=lang)
+    if pkg_root.exists() and EMITS_INIT_FILES[lang]:
+        rebuild_tier_inits(pkg_root)
+    history_files.extend(written)
+    turn_log.append({"turn": 0, "prompt": prompt, "files_written": written,
+                     "raw_response_chars": len(response),
+                     "parse_retried": parse_retried})
+
+    # ── Lane A W3 — Compiler Feedback Loop, after turn 0 ────────────────
+    fix_rounds_log: list[dict[str, Any]] = []
+    if max_fix_rounds > 0 and apply:
+        rounds = _run_fix_rounds(
+            pkg_root=pkg_root, output=output, package=package,
+            language=lang, llm=llm, sys_prompt=sys_prompt,
+            max_fix_rounds=max_fix_rounds, transcript=transcript, turn=0,
+        )
+        for r in rounds:
+            history_files.extend(r.get("files_written", []))
+        fix_rounds_log.extend({**r, "turn": 0} for r in rounds)
+
+    # ── Iteration turns ────────────────────────────────────────────────────
+    final_wire: dict[str, Any] | None = None
+    final_cert: dict[str, Any] | None = None
+    converged = False
+
+    for turn in range(1, max_iterations + 1):
+        wire = scan_violations(pkg_root)
+        cert = certify(output, project=package, package=package)
+        # Walk the *generated* package to compute reuse + emergent context.
+        emitted_scout = harvest_repo(pkg_root) if pkg_root.exists() else None
+        reuse = compute_reuse_stats(emitted_scout, seed_catalog)
+        emergent: dict[str, Any] | None = None
+        if _HAS_EMERGENT and pkg_root.exists():
+            try:
+                emergent = emergent_overlay_for_path(
+                    output, phase="iterate", package=package,
+                )
+            except Exception:  # noqa: BLE001
+                emergent = None
+        final_wire, final_cert = wire, cert
+
+        if wire["verdict"] == "PASS" and cert["score"] >= target_score:
+            converged = True
+            break
+
+        feedback = pack_feedback(wire_report=wire, certify_report=cert,
+                                   emergent_overlay=emergent,
+                                   reuse_stats=reuse,
+                                   iteration=turn)
+        if transcript:
+            transcript.append("prompt", feedback, role="user", llm=llm.name,
+                              extra={"turn": turn, "phase": "iterate"})
+        response = llm.call(feedback, system=sys_prompt)
+        if transcript:
+            transcript.append("response", response, role="assistant",
+                              llm=llm.name, extra={"turn": turn})
+        files = parse_files_from_response(response)
+        if not files:
+            turn_log.append({"turn": turn, "prompt_chars": len(feedback),
+                             "files_written": [], "signal": "llm_done"})
+            break
+        written = _write_files(output, files, language=lang)
+        if pkg_root.exists() and EMITS_INIT_FILES[lang]:
+            rebuild_tier_inits(pkg_root)
+        history_files.extend(written)
+        turn_log.append({"turn": turn, "prompt_chars": len(feedback),
+                         "files_written": written,
+                         "raw_response_chars": len(response)})
+        # Lane A W3 — fix-round budget per turn.
+        if max_fix_rounds > 0:
+            rounds = _run_fix_rounds(
+                pkg_root=pkg_root, output=output, package=package,
+                language=lang, llm=llm, sys_prompt=sys_prompt,
+                max_fix_rounds=max_fix_rounds, transcript=transcript,
+                turn=turn,
+            )
+            for r in rounds:
+                history_files.extend(r.get("files_written", []))
+            fix_rounds_log.extend({**r, "turn": turn} for r in rounds)
+
+    quality_phases: list[dict[str, Any]] = []
+    if lang == "python":
+        docstrings = apply_docstring_phase(pkg_root)
+        quality_phases.append(docstrings)
+        for rel in docstrings.get("files_changed", []):
+            try:
+                history_files.append(str((pkg_root / rel).relative_to(output).as_posix()))
+            except ValueError:
+                pass
+        if docstrings.get("files_changed") and pkg_root.exists():
+            rebuild_tier_inits(pkg_root)
+
+        docs = apply_docs_phase(
+            output_root=output,
+            package_root=pkg_root,
+            package=package,
+            intent=intent,
+        )
+        quality_phases.append(docs)
+        history_files.extend(docs.get("files_written", []))
+
+        tests = apply_test_phase(
+            output_root=output,
+            package_root=pkg_root,
+            package=package,
+        )
+        quality_phases.append(tests)
+        history_files.extend(tests.get("files_written", []))
+
+        final_wire = scan_violations(pkg_root)
+        final_cert = certify(output, project=package, package=package)
+    else:
+        quality_phases.append({
+            "phase": "quality",
+            "language": lang,
+            "skipped": "deterministic doc/test phase is Python-only today",
+        })
+
+    ManifestStore(output).save("quality", {
+        "schema_version": "atomadic-forge.quality/v1",
+        "package": package,
+        "language": lang,
+        "phases": quality_phases,
+        "generated_at_utc": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+    })
+
+    report: dict[str, Any] = {
+        "schema_version": "atomadic-forge.iterate/v1",
+        "applied": True,
+        "intent": intent,
+        "package": package,
+        "language": lang,
+        "output_root": str(output),
+        "llm": llm.name,
+        "iterations": len(turn_log),
+        "files_written_total": len(set(history_files)),
+        "converged": converged,
+        "quality_phases": quality_phases,
+        "final_wire": final_wire,
+        "final_certify": {
+            "score": (final_cert or {}).get("score", 0),
+            "issues": (final_cert or {}).get("issues", []),
+        },
+        "transcript": turn_log,
+        "fix_rounds": fix_rounds_log,
+        "fix_round_count": len(fix_rounds_log),
+        "max_fix_rounds": max_fix_rounds,
+        "transcript_log_path": (str(transcript.path) if transcript else None),
+        "generated_at_utc": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+    }
+    ManifestStore(output).save("iterate", report)
+    return report