atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/doc_synthesizer.py

@@ -0,0 +1,205 @@
+"""Tier a1 — pure renderer that builds a stunning README from a generated package.
+
+After evolve converges, Forge walks the produced package and synthesises a
+showcase-quality README from the actual code, tests, and certify report.
+This replaces the bare scaffolded README with one that reflects what was
+actually built — function names, class signatures, working CLI invocation,
+score breakdown, evidence.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+
+def _collect_public_symbols(package_root: Path) -> dict[str, list[dict[str, str]]]:
+    """Return ``{tier: [{name, kind, signature, doc}]}`` for the package."""
+    out: dict[str, list[dict[str, str]]] = {}
+    for tier_dir in sorted(package_root.iterdir()):
+        if not tier_dir.is_dir():
+            continue
+        if not tier_dir.name.startswith(("a0_", "a1_", "a2_", "a3_", "a4_")):
+            continue
+        items: list[dict[str, str]] = []
+        for py in sorted(tier_dir.glob("*.py")):
+            if py.name == "__init__.py":
+                continue
+            try:
+                tree = ast.parse(py.read_text(encoding="utf-8"))
+            except (SyntaxError, OSError):
+                continue
+            for node in tree.body:
+                if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                    if node.name.startswith("_"):
+                        continue
+                    sig = _function_signature(node)
+                    items.append({
+                        "name": node.name, "kind": "function", "signature": sig,
+                        "doc": (ast.get_docstring(node) or "").split("\n")[0],
+                        "module": py.stem,
+                    })
+                elif isinstance(node, ast.ClassDef) and not node.name.startswith("_"):
+                    items.append({
+                        "name": node.name, "kind": "class",
+                        "signature": f"class {node.name}",
+                        "doc": (ast.get_docstring(node) or "").split("\n")[0],
+                        "module": py.stem,
+                    })
+        if items:
+            out[tier_dir.name] = items
+    return out
+
+
+def _function_signature(fn: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    args: list[str] = []
+    for arg in fn.args.args:
+        if arg.arg in ("self", "cls"):
+            continue
+        ann = ast.unparse(arg.annotation) if arg.annotation else None
+        args.append(f"{arg.arg}: {ann}" if ann else arg.arg)
+    ret = ast.unparse(fn.returns) if fn.returns else "Any"
+    return f"def {fn.name}({', '.join(args)}) -> {ret}"
+
+
+_TIER_LABEL = {
+    "a0_qk_constants": "a0 — constants",
+    "a1_at_functions": "a1 — pure functions",
+    "a2_mo_composites": "a2 — stateful classes",
+    "a3_og_features": "a3 — feature orchestrators",
+    "a4_sy_orchestration": "a4 — CLI / entry points",
+}
+
+
+def render_showcase_readme(*, package: str, intent: str,
+                            output_root: Path,
+                            certify_report: dict[str, Any] | None = None,
+                            cli_demo: dict[str, Any] | None = None,
+                            llm_name: str = "?") -> str:
+    """Build a stunning README for a generated package.
+
+    ``cli_demo`` (optional): ``{"command": [...], "stdout": "...", "rc": int}``
+    captured from a successful invocation of the generated CLI.
+    """
+    pkg_root = output_root / "src" / package
+    symbols = _collect_public_symbols(pkg_root) if pkg_root.exists() else {}
+
+    # Build a hero score badge from the certify report.
+    score_line = ""
+    if certify_report:
+        score = certify_report.get("score", 0)
+        comps = certify_report.get("score_components", {})
+        score_line = (
+            f"![score](https://img.shields.io/badge/forge_certify-"
+            f"{int(score)}%2F100-brightgreen)"
+            if score >= 80 else
+            f"![score](https://img.shields.io/badge/forge_certify-"
+            f"{int(score)}%2F100-yellow)"
+        )
+
+    lines: list[str] = [
+        f"# `{package}`",
+        "",
+        score_line,
+        "",
+        "_Generated by [Atomadic Forge](https://atomadic.tech) — absorb · enforce · emerge._",
+        "",
+        "## Intent",
+        "",
+        f"> {intent.strip()}",
+        "",
+    ]
+
+    if certify_report:
+        score = certify_report.get("score", 0)
+        comps = certify_report.get("score_components", {})
+        (certify_report.get("detail") or {}).get("import_smoke") or {}
+        test_run = (certify_report.get("detail") or {}).get("test_run") or {}
+        lines.extend([
+            "## Forge certification",
+            "",
+            "| Component | Result |",
+            "|-----------|--------|",
+            f"| Documentation present | {'✅' if certify_report.get('documentation_complete') else '❌'} |",
+            f"| Tests present         | {'✅' if certify_report.get('tests_present') else '❌'} |",
+            f"| 5-tier layout         | {'✅' if certify_report.get('tier_layout_present') else '❌'} |",
+            f"| Wire (no upward imports) | {'✅' if certify_report.get('no_upward_imports') else '❌'} |",
+            f"| Package importable    | {'✅' if certify_report.get('package_importable') else '❌'} |",
+            f"| No stub bodies        | {'✅' if certify_report.get('no_stub_bodies') else '❌'} |",
+            f"| Tests pass-ratio      | {certify_report.get('test_pass_ratio', 0):.0%} ({test_run.get('passed', 0)}/{test_run.get('total', 0)}) |",
+            "",
+            f"**Score: {score:.0f}/100** "
+            + (f"(structural {comps.get('structural', 0)} · "
+                f"runtime {comps.get('runtime', 0)} · "
+                f"behavioral {comps.get('behavioral', 0)})"
+                if comps else ""),
+            "",
+        ])
+
+    # Surface the generated symbols, organised by tier.
+    if symbols:
+        lines.append("## What was built")
+        lines.append("")
+        for tier in ("a0_qk_constants", "a1_at_functions", "a2_mo_composites",
+                      "a3_og_features", "a4_sy_orchestration"):
+            if tier not in symbols:
+                continue
+            lines.append(f"### {_TIER_LABEL[tier]}")
+            lines.append("")
+            for s in symbols[tier]:
+                doc = s["doc"] or ""
+                trailer = f" — _{doc}_" if doc else ""
+                lines.append(f"- **`{s['signature']}`**{trailer}  "
+                              f"<sub>(`{tier}/{s['module']}.py`)</sub>")
+            lines.append("")
+
+    if cli_demo:
+        lines.extend([
+            "## Live invocation",
+            "",
+            "```bash",
+            "$ " + " ".join(cli_demo.get("command", []))[:200],
+            (cli_demo.get("stdout") or "").strip()[:500] or "(no stdout)",
+            "```",
+            "",
+            f"Exit code: `{cli_demo.get('rc', '?')}`",
+            "",
+        ])
+
+    lines.extend([
+        "## Architecture",
+        "",
+        "This package follows the Atomadic 5-tier monadic standard.  Every",
+        "file lives in exactly one tier and tiers compose **upward only**.",
+        "Every public symbol is reachable via the tier package's "
+        "auto-generated `__init__.py` re-exports.",
+        "",
+        "```",
+        f"src/{package}/",
+        "├── a0_qk_constants/    constants, enums, TypedDicts",
+        "├── a1_at_functions/    pure stateless functions",
+        "├── a2_mo_composites/   stateful classes",
+        "├── a3_og_features/     feature orchestrators",
+        "└── a4_sy_orchestration/ CLI / entry points",
+        "```",
+        "",
+        "## Install",
+        "",
+        "```bash",
+        "pip install -e .",
+        "```",
+        "",
+        "## Verify with Forge",
+        "",
+        "```bash",
+        f"forge wire src/{package}",
+        f"forge certify . --package {package}",
+        "```",
+        "",
+        "---",
+        "",
+        f"_Generated by Atomadic Forge with `{llm_name}` as the generation engine._",
+        "",
+    ])
+    return "\n".join(line for line in lines if line is not None)

atomadic_forge/a1_at_functions/emergent_compose.py

@@ -0,0 +1,192 @@
+"""Tier a1 — pure composition discovery.
+
+Given a list of :class:`SymbolSignatureCard`, find chains where the output of
+one symbol is type-compatible with an input of another.
+
+Type compatibility is intentionally loose — we work on annotation text:
+
+* exact identical text                  → match
+* ``T`` ↔ ``Optional[T]`` / ``T | None`` → match
+* ``Iterable[T]`` ↔ ``list[T]`` / ``Sequence[T]`` / ``Collection[T]`` → match (T equal)
+* ``Any`` ↔ anything                    → match
+* generic vs concrete (``list`` ↔ ``list[str]``) → match (looser side wins)
+
+Chain enumeration is bounded to depth ``max_depth`` (default 3) so the search
+space stays tractable even on a 600-symbol catalog.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ..a0_qk_constants.emergent_types import (
+    CompositionChain,
+    SymbolSignatureCard,
+)
+
+_OPTIONAL_RE = re.compile(r"^Optional\[(.+)\]$|^(.+)\s*\|\s*None$|^None\s*\|\s*(.+)$")
+_GENERIC_RE = re.compile(r"^(\w+)\[(.+)\]$")
+_COLLECTION_FAMILY = {"list", "List", "Sequence", "Iterable", "Collection",
+                      "tuple", "Tuple", "set", "Set", "frozenset"}
+
+
+def _strip_optional(t: str) -> str:
+    t = t.strip()
+    m = _OPTIONAL_RE.match(t)
+    if m:
+        return next(g for g in m.groups() if g is not None).strip()
+    return t
+
+
+def _outer(t: str) -> tuple[str, str | None]:
+    """Return (outer name, inner) for ``Outer[Inner]``, else (t, None)."""
+    m = _GENERIC_RE.match(t.strip())
+    if not m:
+        return t.strip(), None
+    return m.group(1), m.group(2).strip()
+
+
+def _normalize(t: str) -> str:
+    return _strip_optional(t).replace(" ", "")
+
+
+def types_compatible(produced: str, consumed: str,
+                     *, strict: bool = False) -> bool:
+    """Return True if the producer's output text can flow into the consumer.
+
+    ``strict`` (default False keeps behaviour permissive for backwards-compat):
+    when True, treat ``Any`` as a non-match unless the partner is also ``Any``,
+    and refuse generic-collection variance unless inner types align.  Strict
+    mode is what :func:`find_chains` uses to filter out the noisy ``dict[str,
+    Any] → dict[str, Any]`` chains that dominate the catalog.
+    """
+    p = _normalize(produced)
+    c = _normalize(consumed)
+    if not p or not c:
+        return False
+    if p == c:
+        return True
+    if "Any" in (p, c):
+        if strict:
+            return False
+        return True
+    p_outer, p_inner = _outer(p)
+    c_outer, c_inner = _outer(c)
+    if p_outer in _COLLECTION_FAMILY and c_outer in _COLLECTION_FAMILY:
+        if p_inner is None and c_inner is None:
+            return True
+        if p_inner is None or c_inner is None:
+            return not strict
+        return types_compatible(p_inner, c_inner, strict=strict)
+    if p_outer == c_outer and (p_inner is None or c_inner is None):
+        return not strict
+    return False
+
+
+def is_anyish(t: str) -> bool:
+    """Is this type spec a noisy 'Any-shaped' carrier?"""
+    n = _normalize(t)
+    if n == "Any":
+        return True
+    outer, inner = _outer(n)
+    if inner and "Any" in inner:
+        return True
+    if outer in {"dict", "Dict", "Mapping"} and (inner is None or "Any" in (inner or "")):
+        return True
+    return False
+
+
+def _consumer_inputs(card: SymbolSignatureCard) -> list[str]:
+    return [t for _, t in card["inputs"]]
+
+
+def find_chains(
+    cards: Iterable[SymbolSignatureCard],
+    *,
+    max_depth: int = 3,
+    max_chains: int = 5_000,
+    require_pure: bool = False,
+    domain_jump_required: bool = False,
+    strict_types: bool = True,
+    drop_anyish_seeds: bool = True,
+) -> list[CompositionChain]:
+    """Enumerate type-compatible chains across the catalog.
+
+    A chain is a sequence ``[c1, c2, …]`` where ``c_{i+1}`` has at least one
+    input compatible with ``c_i``'s output, and no card appears twice.
+
+    Parameters bound the search:
+
+    * ``max_depth`` — chain length cap.
+    * ``max_chains`` — early-stop hard cap on returned chains.
+    * ``require_pure`` — only purely-inferred symbols can participate.
+    * ``domain_jump_required`` — at least two distinct domains in the chain.
+    * ``strict_types`` — refuse ``Any``-as-bridge matches.  Cuts the noise
+      from ``dict[str, Any] → dict[str, Any]`` chains that dominate the
+      catalog when most signatures are loosely typed.
+    * ``drop_anyish_seeds`` — skip seeding chains from symbols whose output
+      is a generic ``dict``/``Mapping``/``Any`` carrier.  Such symbols are
+      bottlenecks (they connect to half the catalog) and produce many
+      look-alike candidates.
+    """
+    catalog = [c for c in cards if not (require_pure and not c["is_pure"])]
+    by_qual = {c["qualname"]: c for c in catalog}
+    out: list[CompositionChain] = []
+
+    def consumers_of(produced: str) -> list[SymbolSignatureCard]:
+        return [
+            c for c in catalog
+            if any(types_compatible(produced, ti, strict=strict_types)
+                   for ti in _consumer_inputs(c))
+        ]
+
+    def extend(prefix: list[SymbolSignatureCard]) -> None:
+        if len(out) >= max_chains:
+            return
+        if len(prefix) >= max_depth:
+            _record(prefix)
+            return
+        last = prefix[-1]
+        nexts = consumers_of(last["output"])
+        used = {c["qualname"] for c in prefix}
+        progressed = False
+        for nxt in nexts:
+            if nxt["qualname"] in used:
+                continue
+            progressed = True
+            extend(prefix + [nxt])
+            if len(out) >= max_chains:
+                return
+        if not progressed:
+            _record(prefix)
+
+    def _record(prefix: list[SymbolSignatureCard]) -> None:
+        if len(prefix) < 2:
+            return
+        domains = [p["domain"] for p in prefix]
+        tiers = [p["tier"] for p in prefix]
+        if domain_jump_required and len(set(domains)) < 2:
+            return
+        bridges: list[str] = []
+        for i in range(len(prefix) - 1):
+            bridges.append(prefix[i]["output"])
+        chain = CompositionChain(
+            chain=[p["qualname"] for p in prefix],
+            bridges=bridges,
+            tiers=tiers,
+            domains=domains,
+            crosses_domains=len(set(domains)),
+            crosses_tiers=len(set(tiers)),
+            final_output_type=prefix[-1]["output"],
+            pure=all(by_qual[q]["is_pure"] for q in (p["qualname"] for p in prefix)),
+        )
+        out.append(chain)
+
+    seeds = [c for c in catalog
+             if not (drop_anyish_seeds and is_anyish(c["output"]))]
+    for seed in seeds:
+        extend([seed])
+        if len(out) >= max_chains:
+            break
+    return out

atomadic_forge/a1_at_functions/emergent_rank.py

@@ -0,0 +1,116 @@
+"""Tier a1 — pure ranker for the Emergent Scan.
+
+Score each :class:`CompositionChain` on how 'emergent' it is, then return
+the top-N as :class:`EmergentCandidateCard`.
+
+Score components (max 100):
+
+* cross-domain bonus      ``+ 10 * (crosses_domains - 1)``     (0..30)
+* cross-tier bonus        ``+ 8  * (crosses_tiers   - 1)``     (0..32)
+* purity bonus            ``+ 10`` if all steps pure
+* depth bonus             ``+ 6  * (len(chain) - 1)``           (0..18)
+* novelty bonus           ``+ 10`` if final output type isn't already
+                          the output of any single existing symbol
+
+Output names are heuristic kebab-case combinations of distinct domains.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+
+from ..a0_qk_constants.emergent_types import (
+    CompositionChain,
+    EmergentCandidateCard,
+    SymbolSignatureCard,
+)
+
+
+def _candidate_id(chain: CompositionChain) -> str:
+    h = hashlib.sha256("→".join(chain["chain"]).encode("utf-8")).hexdigest()
+    return f"emrg-{h[:8]}"
+
+
+def _suggest_name(chain: CompositionChain) -> str:
+    seen: list[str] = []
+    for d in chain["domains"]:
+        if d not in seen:
+            seen.append(d)
+    return "-".join(seen[:4]) + "-pipeline"
+
+
+def _suggested_tier(chain: CompositionChain) -> str:
+    """A composition that touches multiple a2 composites is itself a3."""
+    tiers = set(chain["tiers"])
+    if "a4_sy_orchestration" in tiers:
+        return "a4_sy_orchestration"
+    if "a3_og_features" in tiers or len(tiers) >= 3:
+        return "a3_og_features"
+    if "a2_mo_composites" in tiers:
+        return "a2_mo_composites"
+    return "a1_at_functions"
+
+
+def _summary(chain: CompositionChain) -> str:
+    domains = " → ".join(chain["domains"])
+    return (f"Compose {len(chain['chain'])} steps across {chain['crosses_domains']} "
+            f"domain(s): {domains}; final output {chain['final_output_type']}")
+
+
+def rank_chains(
+    chains: Iterable[CompositionChain],
+    *,
+    catalog: list[SymbolSignatureCard],
+    top_n: int = 25,
+    novelty_unknown_outputs: bool = True,
+) -> list[EmergentCandidateCard]:
+    from .emergent_compose import is_anyish
+
+    chains = list(chains)
+    existing_outputs = {c["output"] for c in catalog}
+
+    out: list[EmergentCandidateCard] = []
+    for chain in chains:
+        breakdown: dict[str, float] = {}
+        breakdown["cross_domain"] = min(30, 10 * max(0, chain["crosses_domains"] - 1))
+        breakdown["cross_tier"] = min(32, 8 * max(0, chain["crosses_tiers"] - 1))
+        breakdown["pure"] = 10 if chain["pure"] else 0
+        breakdown["depth"] = min(18, 6 * max(0, len(chain["chain"]) - 1))
+        novelty_signals: list[str] = []
+        novel = (chain["final_output_type"] not in existing_outputs)
+        breakdown["novelty"] = 10 if (novelty_unknown_outputs and novel) else 0
+        # Penalty for chains whose every bridge is Any-shaped — they're real
+        # but uninformative.
+        anyish_bridges = sum(1 for b in chain["bridges"] if is_anyish(b))
+        if anyish_bridges:
+            breakdown["any_penalty"] = -min(20, 6 * anyish_bridges)
+        if novel:
+            novelty_signals.append("final output type not produced by any single existing symbol")
+        if chain["crosses_domains"] >= 3:
+            novelty_signals.append("touches three or more domains")
+        if chain["crosses_tiers"] >= 3:
+            novelty_signals.append("spans three or more tiers")
+        if chain["pure"]:
+            novelty_signals.append("entirely pure — safe to materialise as a1/a3 with no I/O risk")
+        score = sum(breakdown.values())
+        if score <= 0:
+            continue
+        out.append(EmergentCandidateCard(
+            candidate_id=_candidate_id(chain),
+            name=_suggest_name(chain),
+            summary=_summary(chain),
+            chain=chain,
+            score=float(score),
+            score_breakdown=breakdown,
+            suggested_tier=_suggested_tier(chain),
+            novelty_signals=novelty_signals,
+        ))
+    out.sort(key=lambda c: c["score"], reverse=True)
+    # Dedupe candidate names, keep top by score per name
+    seen: dict[str, EmergentCandidateCard] = {}
+    for c in out:
+        if c["name"] not in seen or seen[c["name"]]["score"] < c["score"]:
+            seen[c["name"]] = c
+    deduped = sorted(seen.values(), key=lambda c: c["score"], reverse=True)
+    return deduped[:top_n]