atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/classify_tier.py

@@ -0,0 +1,115 @@
+"""Tier a1 — pure tier classification.
+
+Word-boundary token matching (the substring-bug-fixed version) plus optional
+body-aware promotion: any class with mutable instance state (``self.<attr>
+= …``) is promoted to ``a2_mo_composites`` regardless of name signals.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_WORD_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*")
+
+_CONTRACT = frozenset({"constant", "const", "schema", "manifest", "token",
+                       "invariant", "proof"})
+_ATOM = frozenset({"button", "textarea", "input", "validator", "validate",
+                   "format", "parse", "atom"})
+_COMPOSITE = frozenset({"engine", "service", "client", "manager", "store",
+                        "hook", "calculator", "molecule"})
+_FEATURE = frozenset({"registry", "gateway", "vault", "module", "feature",
+                      "workflow", "page", "screen", "organism"})
+_ORCHESTRATION = frozenset({"server", "router", "orchestrator", "bridge",
+                            "runtime", "system", "main", "mcp", "cli"})
+
+
+def word_tokens(text: str) -> set[str]:
+    """Tokenize on word boundaries and split camelCase.
+
+    ``"AgenticSwarm"`` → ``{"agentic", "swarm"}``; ``"atomadic-v2"`` →
+    ``{"atomadic", "v2"}`` — no false-positive on ``"atom"``.
+    """
+    raw = _WORD_RE.findall(text)
+    out: set[str] = set()
+    for word in raw:
+        for piece in re.findall(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z0-9]+|[A-Z]+", word):
+            if piece:
+                out.add(piece.lower())
+        out.add(word.lower())
+    return out
+
+
+def classify_tier(*, name: str, kind: str, path: str = "",
+                  body_signals: dict[str, Any] | None = None) -> str:
+    """Return the canonical tier directory for a symbol.
+
+    ``body_signals`` (optional) carries ``has_self_assign`` /
+    ``has_class_attr_collections`` flags from the body extractor.  When set,
+    a class with mutable instance state is forced to a2.
+    """
+    tokens = word_tokens(f"{path} {name} {kind}")
+    stateful = bool(body_signals and (
+        body_signals.get("has_self_assign")
+        or body_signals.get("has_class_attr_collections")
+    ))
+
+    if kind in ("class", "type") and stateful:
+        if tokens & _ORCHESTRATION:
+            return "a4_sy_orchestration"
+        if tokens & _FEATURE:
+            return "a3_og_features"
+        return "a2_mo_composites"
+
+    if tokens & _CONTRACT:
+        return "a0_qk_constants"
+    if tokens & _ATOM:
+        return "a1_at_functions"
+    if tokens & _COMPOSITE:
+        return "a2_mo_composites"
+    if tokens & _FEATURE:
+        return "a3_og_features"
+    if tokens & _ORCHESTRATION:
+        return "a4_sy_orchestration"
+
+    if kind == "function":
+        return "a1_at_functions"
+    if kind in ("class", "type"):
+        return "a2_mo_composites"
+    return "a1_at_functions"
+
+
+_IO_ROOT_MODULES = frozenset({"urllib", "requests", "httpx", "socket",
+                              "subprocess", "shutil", "os", "sqlite3",
+                              "boto3", "smtplib"})
+_IO_BUILTINS = frozenset({"open", "print", "input", "connect"})
+
+
+def detect_effects(node: Any) -> list[str]:
+    """Cheap effect inference on an ``ast.AST`` node body."""
+    import ast
+
+    effects: list[str] = []
+    for child in ast.walk(node):
+        if isinstance(child, ast.Call):
+            f = child.func
+            if isinstance(f, ast.Name) and f.id in _IO_BUILTINS:
+                effects.append("io")
+            elif isinstance(f, ast.Attribute):
+                root = f
+                while isinstance(root, ast.Attribute):
+                    root = root.value
+                if isinstance(root, ast.Name) and root.id in _IO_ROOT_MODULES:
+                    effects.append("io")
+                if f.attr in ("write", "send", "post", "put", "delete",
+                               "execute", "commit"):
+                    effects.append("state")
+        if isinstance(child, ast.Global | ast.Nonlocal):
+            effects.append("state")
+    if not effects:
+        return ["pure"]
+    seen: list[str] = []
+    for e in effects:
+        if e not in seen:
+            seen.append(e)
+    return seen

atomadic_forge/a1_at_functions/commandsmith_discover.py

@@ -0,0 +1,167 @@
+"""Tier a1 — pure discovery for the Commandsmith CLI registry.
+
+Walks a directory tree of would-be command modules and returns a list of
+:class:`RegisteredCommandCard` describing what each module exports.
+
+Three recognised surfaces:
+
+* **typer_app** — module exposes a top-level ``app: typer.Typer``.
+* **register_fn** — module exposes ``register(app: typer.Typer) -> None``.
+* **wrapped_class** — module exposes a public class plus a class-level
+  ``COMMAND_NAME`` attribute, indicating it should be wrapped by the
+  generator (see ``commandsmith_render``).
+
+This module is pure: it only reads files and parses AST.  It NEVER imports
+the modules it describes — that lives in tier a2 / a3 to keep a1 import-safe.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+from pathlib import Path
+
+from ..a0_qk_constants.commandsmith_types import (
+    CommandSignatureCard,
+    RegisteredCommandCard,
+)
+
+_PUBLIC = lambda name: not name.startswith("_")  # noqa: E731 — short pure helper
+
+
+def _module_for(path: Path, package_root: Path, package: str) -> str:
+    rel = path.relative_to(package_root)
+    parts = list(rel.with_suffix("").parts)
+    if parts and parts[-1] == "__init__":
+        parts.pop()
+    return ".".join([package, *parts]) if parts else package
+
+
+def _docstring_first_line(node: ast.AST) -> str:
+    doc = ast.get_docstring(node) or ""
+    first = doc.strip().split("\n", 1)[0] if doc else ""
+    return first.strip()
+
+
+def _collect_signature(fn: ast.FunctionDef) -> CommandSignatureCard:
+    params: list[str] = []
+    for arg in fn.args.args:
+        ann = ast.unparse(arg.annotation) if arg.annotation else "Any"
+        params.append(f"{arg.arg}: {ann}")
+    ret = ast.unparse(fn.returns) if fn.returns else "Any"
+    return CommandSignatureCard(
+        name=fn.name,
+        parameters=params,
+        return_type=ret,
+        docstring=_docstring_first_line(fn),
+    )
+
+
+def _detect_surface(tree: ast.Module) -> tuple[str, str, bool, list[ast.AST], str]:
+    """Return (surface, help_text, hidden, sub_command_nodes, command_name)."""
+    has_typer_app = False
+    has_register_fn = False
+    has_command_name_const = False
+    command_name = ""
+    help_text = _docstring_first_line(tree)
+    hidden = False
+    classes: list[ast.ClassDef] = []
+    register_fn: ast.FunctionDef | None = None
+
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    if target.id == "app":
+                        has_typer_app = True
+                    elif target.id == "COMMAND_NAME":
+                        has_command_name_const = True
+                        if isinstance(node.value, ast.Constant) and isinstance(
+                            node.value.value, str
+                        ):
+                            command_name = node.value.value
+                    elif target.id == "COMMAND_HELP":
+                        if isinstance(node.value, ast.Constant) and isinstance(
+                            node.value.value, str
+                        ):
+                            help_text = node.value.value
+                    elif target.id == "COMMAND_HIDDEN":
+                        if isinstance(node.value, ast.Constant) and isinstance(
+                            node.value.value, bool
+                        ):
+                            hidden = node.value.value
+        elif isinstance(node, ast.FunctionDef) and node.name == "register":
+            has_register_fn = True
+            register_fn = node
+        elif isinstance(node, ast.ClassDef) and _PUBLIC(node.name):
+            classes.append(node)
+
+    if has_typer_app:
+        return ("typer_app", help_text, hidden, [], command_name)
+    if has_register_fn:
+        nodes: list[ast.AST] = [register_fn] if register_fn else []
+        return ("register_fn", help_text, hidden, nodes, command_name)
+    if has_command_name_const and classes:
+        classes[0]._commandsmith_name = command_name  # type: ignore[attr-defined]
+        return ("wrapped_class", help_text, hidden, classes, command_name)
+    return ("", "", False, [], "")
+
+
+def discover_command_modules(
+    package_root: Path,
+    package: str,
+    sub_dirs: Iterable[str] = ("commands",),
+    source_root: str = "atomadic_forge_seed",
+) -> list[RegisteredCommandCard]:
+    """Scan ``<package_root>/<sub_dir>`` files for command surfaces.
+
+    Returns a sorted list of :class:`RegisteredCommandCard`.
+    Files starting with ``_`` (incl. ``__init__.py``) are ignored.
+    """
+    cards: list[RegisteredCommandCard] = []
+    for sub in sub_dirs:
+        base = package_root / sub
+        if not base.exists():
+            continue
+        for py_file in sorted(base.rglob("*.py")):
+            if py_file.name.startswith("_"):
+                continue
+            try:
+                tree = ast.parse(py_file.read_text(encoding="utf-8"))
+            except (SyntaxError, OSError):
+                continue
+            surface, help_text, hidden, sub_nodes, explicit_name = _detect_surface(tree)
+            if not surface:
+                continue
+            sub_cmds: list[CommandSignatureCard] = []
+            for node in sub_nodes:
+                if isinstance(node, ast.FunctionDef):
+                    sub_cmds.append(_collect_signature(node))
+                elif isinstance(node, ast.ClassDef):
+                    for body in node.body:
+                        if isinstance(body, ast.FunctionDef) and _PUBLIC(body.name):
+                            sub_cmds.append(_collect_signature(body))
+            name = py_file.stem
+            if surface == "wrapped_class":
+                cls = next(
+                    (c for c in sub_nodes if isinstance(c, ast.ClassDef)), None
+                )
+                custom = getattr(cls, "_commandsmith_name", "") if cls else ""
+                if custom:
+                    name = custom
+            # Explicit COMMAND_NAME wins for any surface (e.g. wrappers strip
+            # the trailing ``_cli`` suffix to expose a cleaner verb).
+            if explicit_name:
+                name = explicit_name
+            cards.append(
+                RegisteredCommandCard(
+                    name=name.replace("_", "-"),
+                    module=_module_for(py_file, package_root, package),
+                    surface=surface,  # type: ignore[arg-type]
+                    help_text=help_text,
+                    hidden=hidden,
+                    sub_commands=sub_cmds,
+                    source_root=source_root,
+                )
+            )
+    return sorted(cards, key=lambda c: c["name"])

atomadic_forge/a1_at_functions/commandsmith_render.py

@@ -0,0 +1,267 @@
+"""Tier a1 — pure renderers for the Commandsmith CLI registry.
+
+Three renderers:
+
+* :func:`render_registry_module` — emits the ``atomadic_forge.commands._registry``
+  Python source that auto-imports each discovered command module and wires
+  it onto the supplied Typer app.
+
+* :func:`render_command_doc` — emits a Markdown page for a single command
+  card.
+
+* :func:`render_command_index` — emits ``docs/commands/INDEX.md`` listing
+  every registered command.
+
+* :func:`render_wrapper_module` — emits a Python source file that wraps a
+  bare class (e.g. an assimilated ``CherryPicker``) in a Typer subcommand
+  group, so newly assimilated features can be invoked from the CLI without
+  hand-coded glue.
+
+All four are pure: they take cards and return strings.  No I/O.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..a0_qk_constants.commandsmith_types import (
+    CommandSignatureCard,
+    RegisteredCommandCard,
+)
+
+_REGISTRY_HEADER = '''"""
+Auto-generated by Commandsmith — do NOT hand-edit.
+Run ``atomadic-forge commandsmith sync`` to refresh.
+"""
+
+from __future__ import annotations
+
+import typer
+
+
+'''
+
+
+def render_registry_module(cards: Iterable[RegisteredCommandCard]) -> str:
+    """Render an importable module that registers every card on a Typer app."""
+    cards = list(cards)
+    imports: list[str] = []
+    body: list[str] = []
+    for card in cards:
+        mod = card["module"]
+        imports.append(f"from {mod} import *  # noqa: F401,F403 — exported via {card['surface']}")
+        # We import the module by full name as alias so different surfaces work
+        # together; collisions are avoided because names are distinct verbs.
+    if not cards:
+        body.append("    pass  # no commands discovered")
+    else:
+        body.append("    \"\"\"Register every Commandsmith-discovered command on ``app``.\"\"\"")
+        for card in cards:
+            mod = card["module"]
+            verb = card["name"]
+            help_text = card["help_text"].replace('"""', "'''")
+            hidden = card["hidden"]
+            if card["surface"] == "typer_app":
+                body.append(
+                    f"    from {mod} import app as _app_{verb.replace('-', '_')}"
+                )
+                body.append(
+                    f"    app.add_typer(_app_{verb.replace('-', '_')}, name={verb!r}, "
+                    f"help={help_text!r}, hidden={hidden!r})"
+                )
+            elif card["surface"] == "register_fn":
+                body.append(f"    from {mod} import register as _reg_{verb.replace('-', '_')}")
+                body.append(
+                    f"    _sub_{verb.replace('-', '_')} = typer.Typer(name={verb!r}, "
+                    f"help={help_text!r})"
+                )
+                body.append(
+                    f"    _reg_{verb.replace('-', '_')}(_sub_{verb.replace('-', '_')})"
+                )
+                body.append(
+                    f"    app.add_typer(_sub_{verb.replace('-', '_')}, name={verb!r}, "
+                    f"hidden={hidden!r})"
+                )
+            elif card["surface"] == "wrapped_class":
+                wrapper_mod = f"{mod}_cli"
+                body.append(
+                    f"    from {wrapper_mod} import app as _wrap_{verb.replace('-', '_')}"
+                )
+                body.append(
+                    f"    app.add_typer(_wrap_{verb.replace('-', '_')}, name={verb!r}, "
+                    f"help={help_text!r}, hidden={hidden!r})"
+                )
+    src = _REGISTRY_HEADER
+    src += "def register_all(app: typer.Typer) -> None:\n"
+    src += "\n".join(body) + "\n"
+    return src
+
+
+def render_command_doc(card: RegisteredCommandCard) -> str:
+    """Render a Markdown page describing one command."""
+    lines = [
+        f"# `atomadic-forge {card['name']}`",
+        "",
+        f"_{card['help_text']}_" if card["help_text"] else "",
+        "",
+        f"- **Module**: `{card['module']}`",
+        f"- **Surface**: `{card['surface']}`",
+        f"- **Source root**: `{card['source_root']}`",
+        f"- **Hidden**: `{card['hidden']}`",
+        "",
+    ]
+    if card["sub_commands"]:
+        lines.append("## Sub-commands")
+        lines.append("")
+        for sc in card["sub_commands"]:
+            lines.append(f"### `{sc['name']}`")
+            lines.append("")
+            if sc["docstring"]:
+                lines.append(sc["docstring"])
+                lines.append("")
+            if sc["parameters"]:
+                lines.append("Parameters:")
+                lines.append("")
+                for p in sc["parameters"]:
+                    lines.append(f"- `{p}`")
+                lines.append("")
+            lines.append(f"Returns: `{sc['return_type']}`")
+            lines.append("")
+    return "\n".join(line for line in lines if line is not None) + "\n"
+
+
+def render_command_index(cards: Iterable[RegisteredCommandCard]) -> str:
+    """Render docs/commands/INDEX.md."""
+    cards = sorted(cards, key=lambda c: c["name"])
+    lines = ["# ASS-ADE Commands", "", "Auto-generated index. One row per top-level CLI verb.", "",
+             "| Verb | Help | Source | Surface |",
+             "|------|------|--------|---------|"]
+    for c in cards:
+        help_short = c["help_text"].replace("|", "\\|") or "_(no help)_"
+        lines.append(
+            f"| `{c['name']}` | {help_short} | `{c['source_root']}` | `{c['surface']}` |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def render_wrapper_module(
+    *,
+    target_module: str,
+    target_class: str,
+    command_name: str,
+    sub_commands: list[CommandSignatureCard],
+    help_text: str = "",
+    init_params: list[str] | None = None,
+    auto_scan: str | None = None,
+) -> str:
+    """Emit a wrapper Python module wrapping a class as a Typer subcommand group.
+
+    Generated app structure::
+
+        app = typer.Typer()
+        @app.callback() — accepts __init__ params, builds an instance, stashes it
+                          on ``ctx.obj``.  Optionally auto-invokes a "warm-up"
+                          method (e.g. ``scan_repo``) before subcommands.
+        @app.command("verb") — pulls instance off ctx.obj, calls the method.
+    """
+    safe_help = help_text.replace('"""', "'''")
+    init_params = init_params or []
+    init_sig, init_fwd = _build_typer_args(init_params)
+    has_init_args = bool(init_fwd)
+
+    lines = [
+        '"""',
+        f"Auto-generated wrapper for {target_module}.{target_class}.",
+        "",
+        f"Run ``atomadic-forge {command_name} <method>`` to invoke methods on this class.",
+        "Re-emit with ``atomadic-forge commandsmith wrap`` after the source changes.",
+        '"""',
+        "",
+        "from __future__ import annotations",
+        "",
+        "import json",
+        "from pathlib import Path  # noqa: F401  — used by some auto-generated annotations",
+        "import typer",
+        "",
+        f"from {target_module} import {target_class}",
+        "",
+        f"COMMAND_NAME = {command_name!r}",
+        f"COMMAND_HELP = {safe_help!r}",
+        "",
+        f'app = typer.Typer(no_args_is_help=True, help={safe_help!r})',
+        "",
+    ]
+
+    # Callback that builds the instance.  Always emitted so subcommands can
+    # share the instance via ctx.obj.
+    cb_args = "ctx: typer.Context"
+    if init_sig:
+        cb_args += ", " + init_sig
+    lines.extend([
+        "@app.callback()",
+        f"def _build({cb_args}) -> None:",
+        f'    """Construct an instance of {target_class} for this invocation."""',
+    ])
+    if has_init_args:
+        lines.append(f"    instance = {target_class}({init_fwd})")
+    else:
+        lines.append(f"    instance = {target_class}()")
+    if auto_scan:
+        lines.append(f"    # auto-warm-up: call {auto_scan}() so subcommands see populated state")
+        lines.append("    try:")
+        lines.append(f"        instance.{auto_scan}()")
+        lines.append("    except Exception:")
+        lines.append("        pass")
+    lines.append("    ctx.obj = instance")
+    lines.append("")
+
+    if not sub_commands:
+        lines.extend([
+            "@app.command('show')",
+            "def _show(ctx: typer.Context) -> None:",
+            f'    """No public methods detected — show the {target_class} repr."""',
+            "    typer.echo(repr(ctx.obj))",
+        ])
+
+    for sc in sub_commands:
+        if sc["name"] in {"__init__"}:
+            continue
+        verb = sc["name"].replace("_", "-")
+        py_args, fwd_args = _build_typer_args(sc["parameters"])
+        full_sig = "ctx: typer.Context"
+        if py_args:
+            full_sig += ", " + py_args
+        doc = sc["docstring"] or f"Invoke {target_class}.{sc['name']}."
+        lines.extend([
+            f"@app.command({verb!r})",
+            f"def _{sc['name']}({full_sig}) -> None:",
+            f'    """{doc}"""',
+            f"    result = ctx.obj.{sc['name']}({fwd_args})",
+            "    if result is not None:",
+            "        try:",
+            "            typer.echo(json.dumps(result, indent=2, default=str))",
+            "        except (TypeError, ValueError):",
+            "            typer.echo(str(result))",
+            "",
+        ])
+    return "\n".join(lines) + "\n"
+
+
+def _build_typer_args(parameters: list[str]) -> tuple[str, str]:
+    """Build (python signature args, forward-call args) from parameter strings.
+
+    Drops ``self``.  Falls back to ``str`` for unknown annotations.
+    """
+    sig_parts: list[str] = []
+    fwd_parts: list[str] = []
+    for p in parameters:
+        name, _, ann = p.partition(":")
+        name = name.strip()
+        ann = ann.strip() or "str"
+        if name in ("self", "cls"):
+            continue
+        if ann not in ("int", "float", "bool", "str", "Path", "list", "dict"):
+            ann = "str"
+        sig_parts.append(f"{name}: {ann}")
+        fwd_parts.append(name)
+    return ", ".join(sig_parts), ", ".join(fwd_parts)

atomadic_forge/a1_at_functions/compiler_feedback.py

@@ -0,0 +1,94 @@
+"""Tier a1 — pure compiler-feedback prompt builder for the fix-round loop.
+
+Golden Path Lane A W3 deliverable. Distinct from the regular iterate
+turn:
+
+  * regular turn   — wire + certify scores → LLM is asked to *improve
+                     quality* (raise the score, fix violations,
+                     etc.). Bounded by ``max_iterations``.
+  * fix-round turn — import_smoke FAIL (or pytest collection error)
+                     → LLM is asked to *fix the broken code* without
+                     adding features. Bounded by ``max_fix_rounds``
+                     PER iterate turn.
+
+A fix-round is much cheaper (one error trace, no quality scoring) and
+should always run before the next regular turn — otherwise the
+regular turn shows the LLM a ``score=0`` because the package didn't
+even import, and the LLM wastes the round chasing scoring instead of
+the actual blocker.
+
+Pure: takes an ``ImportSmokeReport`` (or ImportSmoke-shaped dict) and
+returns a string. No I/O, no LLM call. The forge_loop orchestrator
+owns when to invoke this.
+"""
+from __future__ import annotations
+
+_FIX_ROUND_HEADER = (
+    "FIX ROUND — your previous emission did not import. Do NOT add "
+    "features; do NOT touch unrelated files. Output ONLY the minimum "
+    "set of files needed to make the package importable.\n"
+)
+
+_FIX_ROUND_FOOTER = (
+    "\nRespond with the standard JSON array of `{path, content}` "
+    "objects. If you believe the package is already correct and the "
+    "error is environmental (e.g. a missing 3rd-party dep), output "
+    "the exact two characters `[]` and the loop will exit.\n"
+)
+
+
+def pack_compile_feedback(
+    smoke_report: dict,
+    *,
+    package: str,
+    fix_round_index: int,
+    max_fix_rounds: int,
+) -> str:
+    """Build the fix-round prompt from an ImportSmokeReport-shape dict.
+
+    Arguments:
+      smoke_report     — dict with at least ``error_kind``,
+                         ``error_message``, ``traceback_excerpt``.
+      package          — the package name being iterated.
+      fix_round_index  — 1-based current attempt within this turn.
+      max_fix_rounds   — total budget so the LLM knows whether to
+                         minimise the fix or give up cleanly.
+    """
+    if fix_round_index < 1:
+        raise ValueError("fix_round_index must be >= 1")
+    if max_fix_rounds < 1:
+        raise ValueError("max_fix_rounds must be >= 1")
+
+    kind = str(smoke_report.get("error_kind") or "ImportFailure")
+    message = str(smoke_report.get("error_message") or "(no message)")
+    trace = str(smoke_report.get("traceback_excerpt") or "").strip()
+
+    parts: list[str] = [
+        _FIX_ROUND_HEADER,
+        f"  package:           {package}",
+        f"  fix-round attempt: {fix_round_index} of {max_fix_rounds}",
+        f"  error_kind:        {kind}",
+        f"  error_message:     {message}",
+    ]
+    if trace:
+        # Cap to avoid blowing the context window — the smoke
+        # collector already trims stderr to ~600 chars.
+        parts.append("\nTraceback excerpt:\n```\n" + trace[:1200] + "\n```")
+    parts.append(_FIX_ROUND_FOOTER)
+    return "\n".join(parts)
+
+
+def should_fix_round(smoke_report: dict) -> bool:
+    """Return True iff the smoke report names a fixable runtime error.
+
+    'Fixable' means: there's a concrete error_kind and non-empty
+    message we can show the LLM. Empty smoke (importable=True) returns
+    False; environmental failures with no useful trace also return
+    False so the orchestrator skips the round rather than re-prompting
+    the LLM with nothing.
+    """
+    if smoke_report.get("importable"):
+        return False
+    kind = smoke_report.get("error_kind") or ""
+    message = smoke_report.get("error_message") or ""
+    return bool(kind and message)