minifactory 0.0.1__py3-none-any.whl

minifactory/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

minifactory/__main__.py

@@ -0,0 +1,3 @@
+from minifactory.cli import main
+
+raise SystemExit(main())

minifactory/catalog.py

@@ -0,0 +1,130 @@
+"""A description of what can be built with the registered plugins, generated from the registry
+itself (so it is never stale): which steps exist, what parameters they take, which providers a
+workflow can configure. It is what the workflow-drafting agent reads, and `plugins --schema` prints."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from .core import registry
+
+# Constructor arguments that are injected by the engine or exist only for tests: not for a workflow author.
+_INTERNAL = {"self", "secrets", "client", "transport", "runner"}
+
+
+def _first_paragraph(obj: Any) -> str:
+    """The class's OWN docstring (an inherited one would describe the base class, not the plugin)."""
+    doc = inspect.cleandoc(obj.__dict__.get("__doc__") or "")
+    return " ".join(doc.split("\n\n")[0].split())
+
+
+def _type(schema: dict[str, Any]) -> str:
+    if "enum" in schema:
+        return "|".join(map(str, schema["enum"]))
+    if "anyOf" in schema:
+        return " | ".join(t for t in (_type(s) for s in schema["anyOf"]) if t != "null") or "null"
+    if schema.get("type") == "array":
+        return f"list[{_type(schema.get('items', {})) or 'any'}]"
+    if "$ref" in schema:
+        return "object"
+    return str(schema.get("type", "any"))
+
+
+def _step_params(cls: Any) -> list[dict[str, Any]]:
+    schema = cls.Params.model_json_schema()
+    required = set(schema.get("required", []))
+    return [{"name": name, "type": _type(spec), "required": name in required,
+             **({"default": spec["default"]} if "default" in spec else {})}
+            for name, spec in schema.get("properties", {}).items()]
+
+
+def _init_params(cls: Any) -> list[dict[str, Any]]:
+    out = []
+    for name, p in inspect.signature(cls.__init__).parameters.items():
+        if name in _INTERNAL or p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD):
+            continue
+        out.append({"name": name, "required": p.default is p.empty,
+                    **({} if p.default is p.empty else {"default": p.default})})
+    return out
+
+
+def describe() -> dict[str, Any]:
+    """{'steps': {name: {doc, needs, params}}, '<kind>': {name: {doc, params}}} for every plugin."""
+    out: dict[str, Any] = {"steps": {}}
+    for name in registry.catalog()["step"]:
+        cls = registry.get("step", name)
+        out["steps"][name] = {"doc": _first_paragraph(cls), "needs": list(cls.needs), "params": _step_params(cls)}
+    for kind in ("scm", "llm", "secrets", "source", "executor", "router", "intake"):
+        out[kind] = {name: {"doc": _first_paragraph(registry.get(kind, name)),
+                            "params": _init_params(registry.get(kind, name))}
+                     for name in registry.catalog()[kind]}
+    return out
+
+
+FORMAT_GUIDE = """\
+# How a workflow is written
+
+A workflow is one YAML file. Only the keys below exist; anything else is an error.
+
+```yaml
+name: my-workflow                 # required, unique
+route:                            # optional: makes `minifactory ask` able to choose it
+  description: one sentence on when to use this workflow
+  not_for: [things it must not be used for]
+  examples: ["a sample request"]
+  needs: what a request must contain for it to start
+  intake: app-spec                # a registered intake that drafts the job input from the text
+  delivery: choose                # or `fixed` when the workflow delivers to its own target
+vars: {key: value}                # constants, read as ${vars.key}
+source: {use: <source>, with: {...}}       # where the jobs come from
+executor: {use: local}                      # optional
+providers:                                  # only the ones the steps need
+  scm: {use: <scm>, with: {...}}
+  llm: {use: <llm>, with: {...}}
+steps:
+  - id: unique_id
+    use: <step name from the list below>
+    with: {param: value}          # exactly the parameters listed for that step
+    when: "steps.build.status == 'failed'"      # optional condition
+    on_fail: fail                 # fail | discard (stop, change nothing) | continue
+    blocking: true                # false: a failure only becomes a note
+```
+
+Rules the validator enforces:
+- `use:` must name a registered step; `with:` keys must be that step's parameters; required ones must be present.
+- A step that lists `needs: [scm]` or `[llm]` requires that provider under `providers:`.
+- Step ids are unique, and `${steps.<id>...}` / `steps.<id>` may only refer to steps that run EARLIER.
+- Templates: `${job.<attr>}`, `${steps.<id>.outputs.<key>}`, `${steps.<id>.status}`, `${vars.<k>}`, `${env.python}`.
+- `when` is a tiny expression language: names, attribute access, literals, comparisons, `in`, `and`/`or`/`not`.
+  No function calls, no indexing, no arithmetic. Loops do not exist.
+- Do not invent steps, providers or parameters. If the goal needs something that is not listed, say so.
+"""
+
+
+def _requirement(p: dict[str, Any]) -> str:
+    if p["required"]:
+        return " (required)"
+    return f" (default {p['default']!r})" if "default" in p else " (optional)"
+
+
+def _params_line(params: list[dict[str, Any]], with_types: bool) -> str:
+    labels = [(f"{p['name']}: {p['type']}" if with_types else p["name"]) + _requirement(p) for p in params]
+    return "; ".join(labels) or "none"
+
+
+def render_markdown() -> str:
+    d = describe()
+    lines = [FORMAT_GUIDE, "# Steps (the only values allowed for `use:` in `steps`)", ""]
+    for name, info in d["steps"].items():
+        needs = f" [needs providers: {', '.join(info['needs'])}]" if info["needs"] else ""
+        lines += [f"## {name}{needs}", info["doc"] or "(no description)",
+                  f"params: {_params_line(info['params'], True)}", ""]
+    lines += ["# Plugins for `source`, `executor` and `providers` (`use:` + `with:` = constructor arguments)", ""]
+    for kind in ("source", "executor", "scm", "llm", "secrets"):
+        for name, info in d[kind].items():
+            lines += [f"## {kind}: {name}", info["doc"] or "(no description)",
+                      f"with: {_params_line(info['params'], False)}", ""]
+    lines += ["# Intakes (for `route.intake`)", ""]
+    lines += [f"- {name}: {info['doc']}" for name, info in d["intake"].items()]
+    return "\n".join(lines) + "\n"

minifactory/cli.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from minifactory import templates, workspace
+from minifactory.core import registry
+from minifactory.core.engine import Engine
+from minifactory.core.errors import FactoryError, RoutingError, VagueRequest
+from minifactory.core.events import ConsoleSink, EventBus
+from minifactory.core.workflow import load_workflow
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="minifactory", description="Tiny pluggable software factory")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    run = sub.add_parser("run", help="run a workflow over all jobs from its source")
+    run.add_argument("workflow", help="a workflow name (from your workspace) or a path to a .yaml")
+    run.add_argument("--runs-dir", help="default: from minifactory.yaml")
+    run.add_argument("--resume", action="store_true", help="skip steps already completed (ok)")
+    run.add_argument("--only", action="append", default=[], help="job id to run (repeatable)")
+    run.add_argument("--limit", type=int, default=0)
+    run.add_argument("--plugin", action="append", default=[], help="extra plugin module to import")
+    run.add_argument("--quiet", action="store_true", help="hide per-step lines")
+    run.add_argument("--plain", action="store_true", help="no colours or live board")
+
+    ask = sub.add_parser("ask", help="describe what you need in plain language; picks and runs a workflow")
+    ask.add_argument("request")
+    ask.add_argument("--workflows-dir", help="default: the workspace workflows folders")
+    ask.add_argument("--router", help="router plugin (default: minifactory.yaml, then jev)")
+    ask.add_argument("--threshold", type=float, help="minimum router confidence (default: minifactory.yaml, then 0.7)")
+    ask.add_argument("--yes", action="store_true", help="don't ask; only acts when confident and actionable")
+    ask.add_argument("--dry-run", action="store_true", help="show the chosen workflow and drafted input, run nothing")
+    ask.add_argument("--output", choices=["local", "github"],
+                     help="where the result goes (asked interactively if omitted)")
+    ask.add_argument("--output-dir", help="parent folder for --output local (default: minifactory.yaml, then output)")
+    ask.add_argument("--owner", help="GitHub user or org for --output github (default: your gh login)")
+    ask.add_argument("--public", action="store_true", help="make the GitHub repo public (default: private)")
+    ask.add_argument("--runs-dir", help="default: from minifactory.yaml")
+    ask.add_argument("--plain", action="store_true", help="no colours or live board")
+    ask.add_argument("--plugin", action="append", default=[])
+
+    val = sub.add_parser("validate", help="check a workflow without running it")
+    val.add_argument("workflow", help="a workflow name or a path to a .yaml")
+    val.add_argument("--plugin", action="append", default=[])
+
+    pl = sub.add_parser("plugins", help="list registered plugins")
+    pl.add_argument("--plugin", action="append", default=[])
+    pl.add_argument("--schema", action="store_true",
+                    help="print what can be built: every step with its parameters, providers, the format rules")
+    pl.add_argument("--json", action="store_true", help="with --schema: machine-readable")
+
+    init = sub.add_parser("init", help="create a workspace (minifactory.yaml + workflows/) in a folder")
+    init.add_argument("folder", nargs="?", default=".")
+    init.add_argument("--template", help="also copy a template workflow (see `minifactory workflows list`)")
+
+    wf = sub.add_parser("workflows", help="list or copy workflows")
+    wf_sub = wf.add_subparsers(dest="wf_cmd", required=True)
+    wf_sub.add_parser("list", help="your workflows and the templates that ship with the package")
+    cp = wf_sub.add_parser("copy", help="copy a packaged template into your workspace")
+    cp.add_argument("name")
+    en = wf_sub.add_parser("enable", help="review a drafted workflow and make it active (routable by `ask`)")
+    en.add_argument("name")
+    en.add_argument("--yes", action="store_true", help="don't ask for confirmation")
+
+    demo = sub.add_parser("demo-init", help="create the demo sandbox (git remotes + catalog)")
+    demo.add_argument("--dir", default="demo")
+    return p
+
+
+def _summary(results) -> None:
+    print("\n" + "─" * 78)
+    print(f"{'JOB':<22} {'OUTCOME':<10} DETAIL")
+    for r in results:
+        pr = r.artifacts[0].ref if r.artifacts else ""
+        detail = pr or r.reason
+        print(f"{r.job_id:<22} {r.outcome:<10} {detail}")
+        for note in r.notes:
+            print(f"{'':<33} note: {note}")
+    counts = {o: sum(r.outcome == o for r in results) for o in ("succeeded", "failed", "discarded")}
+    print("─" * 78)
+    print("  ".join(f"{k}: {v}" for k, v in counts.items()))
+
+
+def _execute(engine: Engine, bus: EventBus, jobs, args) -> None:
+    """Run jobs with the live board on a terminal, plain lines otherwise."""
+
+    def run_one(job):
+        return engine.run_job(job, resume=getattr(args, "resume", False))
+
+    spec = engine.spec
+    if sys.stdout.isatty() and not args.plain:
+        from minifactory.ui import LiveBoard, banner
+
+        board = LiveBoard([j.id for j in jobs], [s.id for s in spec.steps])
+        banner(board.console)
+        board.console.print(f"[bold]{spec.name}[/]  ·  {len(jobs)} job(s)\n")
+        bus.subscribe(board)
+        with board:
+            results = engine.executor.run(jobs, run_one)
+        board.summary(results)
+        return
+
+    if not getattr(args, "quiet", False):
+        bus.subscribe(ConsoleSink())
+    print(f"workflow '{spec.name}': {len(jobs)} job(s)")
+    results = engine.executor.run(jobs, run_one)
+    _summary(results)
+
+
+def _pick_output(console, args) -> str | None:
+    console.print(f"Where should the result go?\n  1. local folder ({args.output_dir}/<name>)\n"
+                  f"  2. a new {'PUBLIC' if args.public else 'private'} GitHub repository + pull request")
+    answer = input("Choose 1 or 2 (empty to abort): ").strip()
+    if answer not in ("1", "2"):
+        console.print("aborted")
+        return None
+    return "local" if answer == "1" else "github"
+
+
+def _ask(args) -> int:
+    from rich.console import Console
+
+    from minifactory import router as R
+    from minifactory.ui import show_decision, show_spec
+
+    console = Console()
+    routables = R.discover(args.workflow_dirs)
+    router = registry.get("router", args.router)()
+    decision = router.choose(args.request, [r.candidate for r in routables.values()])
+    show_decision(console, decision, args.threshold)
+    if decision.usage:
+        console.print(f"[dim]router tokens: {decision.usage}[/]")
+
+    interactive = sys.stdin.isatty() and not args.yes
+    try:
+        R.check(decision, args.threshold)
+        choice = decision.choice
+    except VagueRequest as problem:
+        if not interactive:
+            raise
+        console.print(f"[yellow]{problem}[/] (you can still review the drafted input below)")
+        choice = decision.choice
+    except RoutingError as problem:
+        ranking = [n for n, _ in R.ranked(decision) if n in routables]
+        if not interactive or not ranking:
+            raise
+        console.print(f"[yellow]{problem}[/]")
+        for i, name in enumerate(ranking, 1):
+            console.print(f"  {i}. {name}")
+        answer = input("Pick a workflow number (empty to abort): ").strip()
+        if not answer.isdigit() or not 1 <= int(answer) <= len(ranking):
+            console.print("aborted")
+            return 2
+        choice = ranking[int(answer) - 1]
+
+    chosen = routables[choice]
+    drafting = Engine(chosen.spec, args.runs_dir, EventBus())  # only for its llm provider
+    engine = drafting
+    if engine.llm is None:
+        raise RoutingError(f"workflow '{chosen.spec.name}' has no llm provider to draft its input")
+    intake = registry.get("intake", chosen.spec.route.intake)()
+    try:
+        job = intake.build(args.request, engine.llm)
+    except ValueError as e:
+        raise RoutingError(str(e)) from None
+    show_spec(console, chosen.spec.name, job)
+
+    output = args.output
+    if chosen.spec.route.delivery == "fixed":
+        if output:
+            raise RoutingError("this workflow delivers to the repository itself; --output does not apply")
+        bus = EventBus()
+        engine = Engine(chosen.spec, args.runs_dir, bus)
+        describe = getattr(engine.scm, "target", lambda repo: repo)  # `target` is optional on providers
+        console.print(f"[bold]delivery →[/] {describe(job.name)}")
+        if args.dry_run:
+            return 0
+        if not args.yes and (not sys.stdin.isatty() or input("Run it? [y/N] ").strip().lower() != "y"):
+            console.print("not run (confirm interactively or pass --yes)")
+            return 2
+        _execute(engine, bus, [job], args)
+        return 0
+    if output is None and not args.dry_run:
+        if not interactive:
+            raise RoutingError("choose where the result goes: --output local|github")
+        output = _pick_output(console, args)
+        if output is None:
+            return 2
+    bus = EventBus()
+    if output:
+        spec = R.with_output(chosen.spec, output, output_dir=args.output_dir, owner=args.owner,
+                             public=args.public)
+        engine = Engine(spec, args.runs_dir, bus)
+        console.print(f"[bold]output →[/] {engine.scm.target(job.name)}")
+        if output == "github" and args.public:
+            console.print("[bold red]this repository will be PUBLIC[/]")
+    if args.dry_run:
+        return 0
+    if not args.yes and (not sys.stdin.isatty() or input("Run it? [y/N] ").strip().lower() != "y"):
+        console.print("not run (confirm interactively or pass --yes)")
+        return 2
+    _execute(engine, bus, [job], args)
+    return 0
+
+
+def _use_workspace(args: argparse.Namespace) -> workspace.Workspace | None:
+    """Find the workspace, fill unset options from its config and make it the working directory
+    (workflows reference specs/, output/... relative to the workspace root). Without a workspace
+    everything stays relative to the current directory, as before."""
+    ws = workspace.find()
+    cfg = ws.config if ws else workspace.FactoryConfig()
+    # Paths typed on the command line mean "relative to where I am": make them absolute first.
+    wf = getattr(args, "workflow", None)
+    if wf and Path(wf).is_file():
+        args.workflow = str(Path(wf).resolve())
+    explicit = getattr(args, "workflows_dir", None)
+    if explicit:
+        args.workflow_dirs = [Path(explicit).resolve()]
+    elif ws:
+        args.workflow_dirs = ws.workflow_dirs
+    else:
+        args.workflow_dirs = [Path.cwd() / cfg.workflows_dir]
+    if ws:
+        os.chdir(ws.root)
+    for attr, default in (("runs_dir", cfg.runs_dir), ("output_dir", cfg.output_dir),
+                          ("router", cfg.router), ("threshold", cfg.threshold)):
+        if hasattr(args, attr) and getattr(args, attr) is None:
+            setattr(args, attr, default)
+    args.plugin = [*cfg.plugins, *getattr(args, "plugin", [])]
+    return ws
+
+
+def _resolve_workflow(name: str, dirs: list[Path]) -> str:
+    """A path to a .yaml, or the name of a workflow in the workspace folders."""
+    if Path(name).is_file():
+        return name
+    for folder in dirs:
+        for candidate in (folder / name, folder / f"{name}.yaml"):
+            if candidate.is_file():
+                return str(candidate)
+    known = sorted(f.stem for folder in dirs for f in folder.glob("*.yaml"))
+    hint = f"your workflows: {', '.join(known)}" if known else "no workflows found"
+    ready = ", ".join(templates.available())
+    raise FactoryError(f"workflow '{name}' not found ({hint}). Templates you can copy: {ready}. "
+                       "See `minifactory workflows list`")
+
+
+def _enable(args: argparse.Namespace, ws: workspace.Workspace | None) -> int:
+    """Show what a drafted workflow would do, then move it into the active workflows folder."""
+    from minifactory.review import review
+
+    if ws is None:
+        raise FactoryError("no workspace here. Run `minifactory init` first")
+    folder = ws.root / ws.config.workflows_dir
+    draft, target = folder / "drafts" / f"{args.name}.yaml", folder / f"{args.name}.yaml"
+    if not draft.is_file():
+        raise FactoryError(f"no draft named '{args.name}' in {draft.parent}")
+    if target.exists():
+        raise FactoryError(f"{target} already exists; remove or rename one of them first")
+    spec = load_workflow(draft)  # a draft written under other plugins may no longer validate
+    print(f"workflow '{spec.name}' ({len(spec.steps)} steps) would be enabled. Review:")
+    for finding in review(spec):
+        print(f"  {finding}")
+    if not args.yes and (not sys.stdin.isatty() or input("Enable it? [y/N] ").strip().lower() != "y"):
+        print("not enabled (confirm interactively or pass --yes)")
+        return 2
+    draft.rename(target)
+    print(f"enabled: {target.relative_to(ws.root)}")
+    return 0
+
+
+def _workflows(args: argparse.Namespace, ws: workspace.Workspace | None) -> int:
+    if args.wf_cmd == "copy":
+        if ws is None:
+            raise FactoryError("no workspace here. Run `minifactory init` first")
+        for path in templates.copy(args.name, ws.root, ws.config.workflows_dir):
+            print(f"  + {path.relative_to(ws.root)}")
+        return 0
+    if args.wf_cmd == "enable":
+        return _enable(args, ws)
+    print("your workflows:")
+    mine = [f for folder in args.workflow_dirs for f in sorted(folder.glob("*.yaml"))]
+    for f in mine:
+        try:
+            spec = load_workflow(f)
+            print(f"  {spec.name:<32} {'routable' if spec.route else 'run only'}   {f}")
+        except FactoryError as e:
+            print(f"  {f.stem:<32} INVALID: {str(e)[:80]}")
+    if not mine:
+        print("  (none)")
+    drafts = [f for folder in args.workflow_dirs for f in sorted((folder / "drafts").glob("*.yaml"))]
+    if drafts:
+        print("\ndrafts (not routable until `minifactory workflows enable NAME`):")
+        for f in drafts:
+            print(f"  {f.stem:<32} {f}")
+    print("\ntemplates (copy with `minifactory workflows copy NAME`):")
+    for t in templates.available().values():
+        print(f"  {t.name:<32} {t.description}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.cmd == "init":
+            folder = Path(args.folder)
+            created = workspace.init(folder)
+            if args.template:
+                root = folder.resolve()
+                created += [str(p.relative_to(root)) for p in templates.copy(args.template, root)]
+            print(f"workspace ready in {folder.resolve()}" + "".join(f"\n  + {c}" for c in created))
+            return 0
+
+        ws = _use_workspace(args)
+        registry.load_plugins(args.plugin)
+        if args.cmd == "workflows":
+            return _workflows(args, ws)
+
+        if args.cmd == "demo-init":
+            from minifactory.demo import demo_init
+
+            path = demo_init(args.dir)
+            print(f"demo sandbox ready in ./{path}")
+            return 0
+
+        if args.cmd == "plugins" and args.schema:
+            from minifactory import catalog as plugin_catalog
+
+            if args.json:
+                import json
+
+                print(json.dumps(plugin_catalog.describe(), indent=2, default=str))
+            else:
+                print(plugin_catalog.render_markdown())
+            return 0
+        if args.cmd == "plugins":
+            catalog = registry.catalog()
+            if sys.stdout.isatty():
+                from rich.console import Console
+                from rich.table import Table
+
+                table = Table(title="registered plugins", header_style="bold magenta")
+                table.add_column("kind", style="cyan")
+                table.add_column("names")
+                for kind, names in catalog.items():
+                    table.add_row(kind, "  ".join(names))
+                Console().print(table)
+            else:
+                for kind, names in catalog.items():
+                    print(f"{kind:<9} {', '.join(names)}")
+            return 0
+
+        if args.cmd == "ask":
+            return _ask(args)
+
+        spec = load_workflow(_resolve_workflow(args.workflow, args.workflow_dirs))
+        if args.cmd == "validate":
+            print(f"workflow '{spec.name}' is valid ({len(spec.steps)} steps)")
+            return 0
+
+        bus = EventBus()
+        engine = Engine(spec, args.runs_dir, bus)
+        jobs = engine.source.jobs()
+        if args.only:
+            jobs = [j for j in jobs if j.id in args.only]
+        if args.limit:
+            jobs = jobs[: args.limit]
+        _execute(engine, bus, jobs, args)
+        return 0
+    except FactoryError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

minifactory/core/context.py

@@ -0,0 +1,43 @@
+"""What a step receives (StepContext) and what a step is (Step)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, ClassVar
+
+from pydantic import BaseModel, ConfigDict
+
+from .models import Job, StepResult
+
+
+class StrictParams(BaseModel):
+    """Base for step parameters: unknown keys are errors, so YAML typos fail fast."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+@dataclass
+class StepContext:
+    job: Job
+    work_dir: Path
+    scm: Any  # SCMProvider | None
+    llm: Any  # LLMProvider | None
+    secrets: Any  # SecretsProvider
+    emit: Callable[..., None]
+    outputs: dict[str, dict[str, Any]] = field(default_factory=dict)  # step id -> outputs
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def repo_dir(self) -> Path:
+        return self.work_dir / "repo"
+
+
+class Step:
+    """Subclass, set Params, implement run(), and register with @register("step", "x.y")."""
+
+    Params: ClassVar[type[BaseModel]] = StrictParams
+    needs: ClassVar[tuple[str, ...]] = ()  # providers required: "scm", "llm"
+
+    def run(self, ctx: StepContext, params: Any) -> StepResult:  # pragma: no cover
+        raise NotImplementedError