buildwright 0.1.0__py3-none-any.whl

buildwright/__init__.py

@@ -0,0 +1,3 @@
+"""Per-agent model routing: cada agent amb el seu model, local o remot."""
+
+__version__ = "0.1.0"

buildwright/agents.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+from pydantic_ai.models import Model
+
+from .config import ROLES, Settings
+from .registry import ModelRegistry
+
+
+class Plan(BaseModel):
+    """Structured output of the planner agent."""
+
+    steps: list[str] = Field(min_length=1, max_length=5)
+    needs_strong_model: bool = Field(
+        default=False,
+        description="true only when the task needs the strong remote model",
+    )
+
+
+class Review(BaseModel):
+    """Structured output of the reviewer agent."""
+
+    verdict: Literal["pass", "fail"]
+    comments: str
+
+
+ModelFactory = Callable[[str], Model]  # role -> Model (tests use TestModel)
+
+
+@dataclass
+class Wright:
+    """Agent factory: each role wired to the model assigned to it in Settings."""
+
+    settings: Settings
+    registry: ModelRegistry | None = None
+    model_factory: ModelFactory | None = None
+
+    def model_for(self, role: str) -> Model:
+        if role not in ROLES:
+            raise KeyError(f"unknown role '{role}'. Known: {', '.join(ROLES)}")
+        if self.model_factory is not None:
+            return self.model_factory(role)
+        assert self.registry is not None, "registry required without model_factory"
+        return self.registry.build(self.settings.role_model(role))
+
+    def planner(self) -> Agent[None, Plan]:
+        return Agent(
+            self.model_for("planner"),
+            output_type=Plan,
+            instructions=(
+                "You are a task planner. Break the user task into 1-5 concrete steps. "
+                "Set needs_strong_model=true only for hard reasoning or code-heavy tasks."
+            ),
+        )
+
+    def worker(self) -> Agent[None, str]:
+        return Agent(
+            self.model_for("worker"),
+            instructions="You are a meticulous engineer. Execute the given step. Be concise.",
+        )
+
+    def reviewer(self) -> Agent[None, Review]:
+        return Agent(
+            self.model_for("reviewer"),
+            output_type=Review,
+            instructions=(
+                "You are a strict reviewer. Judge the work against the task; "
+                "reply verdict pass or fail with short comments."
+            ),
+        )

buildwright/cli.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .agents import Wright
+from .config import ROLES, Settings
+from .graph import build_graph
+from .observability import get_tracer
+from .registry import ModelRegistry
+
+
+def _wright(settings: Settings) -> Wright:
+    registry = ModelRegistry.load(settings.models_file)
+    return Wright(settings=settings, registry=registry)
+
+
+def cmd_models(settings: Settings) -> None:
+    registry = ModelRegistry.load(settings.models_file)
+    for kind in ("local", "remote"):
+        print(f"\n{kind.upper()}")
+        for s in registry.list(kind):
+            key = f"  [key: {s.api_key_env}]" if s.api_key_env else ""
+            print(f"  {s.id:<24} {s.label}{key}")
+
+
+def cmd_roles(settings: Settings) -> None:
+    ModelRegistry.load(settings.models_file)  # validates the file
+    print("\nrole         model-id                model wire")
+    registry = ModelRegistry.load(settings.models_file)
+    for role in ROLES:
+        model_id = settings.role_model(role)
+        wire = registry.spec(model_id).model or model_id.split("/", 1)[1]
+        print(f"{role:<12} {model_id:<24} {wire}")
+
+
+def cmd_ask(settings: Settings, task: str) -> None:
+    board = _wright(settings)
+    graph = build_graph(board)
+    tracer = get_tracer(settings)
+
+    with tracer.span("buildwright.ask", task=task):
+        state = graph.invoke({"task": task})
+
+    plan = state["plan"]
+    print("\n--- plan", f"({settings.role_model('planner')}) ---")
+    for i, step in enumerate(plan.steps, 1):
+        print(f"  {i}. {step}")
+    print("\n--- answer", f"({settings.role_model('worker')}) ---")
+    print(state["answer"])
+    review = state["review"]
+    print(f"\n--- review ({settings.role_model('reviewer')}): {review.verdict} ---")
+    print(f"  {review.comments}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="buildwright",
+        description="Per-agent model routing: one model per role, local and remote in the same registry.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("models", help="list the models in the registry")
+    sub.add_parser("roles", help="show the role -> model mapping")
+    ask = sub.add_parser("ask", help="run the plan -> execute -> review pipeline")
+    ask.add_argument("task")
+
+    args = parser.parse_args(argv)
+    settings = Settings()
+
+    try:
+        if args.cmd == "models":
+            cmd_models(settings)
+        elif args.cmd == "roles":
+            cmd_roles(settings)
+        else:
+            cmd_ask(settings, args.task)
+    except (KeyError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

buildwright/config.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+ROLES = ("planner", "worker", "reviewer")
+
+
+def default_models_file() -> Path:
+    """Registry resolution: project-local ./models.yaml > the bundled models.yaml."""
+    local = Path("models.yaml")
+    if local.is_file():
+        return local
+    return Path(str(resources.files("buildwright").joinpath("models.yaml")))
+
+
+class Settings(BaseSettings):
+    """Central configuration. The role->model mapping is the switchboard itself."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="BW_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    models_file: Path = Field(default_factory=default_models_file)
+
+    # role -> registry id (models.yaml)
+    role_planner: str = "local/qwen3"
+    role_worker: str = "remote/gpt-4o-mini"
+    role_reviewer: str = "local/qwen3"
+
+    # Langfuse: no keys -> tracing disabled (NullTracer)
+    langfuse_public_key: str | None = None
+    langfuse_secret_key: str | None = None
+    langfuse_host: str = "http://localhost:3000"
+
+    def role_model(self, role: str) -> str:
+        value = getattr(self, f"role_{role}", None)
+        if value is None:
+            raise KeyError(f"unknown role '{role}'. Known: {', '.join(ROLES)}")
+        return value
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

buildwright/graph.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+from .agents import Plan, Review, Wright
+
+# Each node is ONE PydanticAI agent; the model is decided by the role
+# (Settings), never by the node. Assembling a CRAG or changing the flow
+# therefore touches zero lines of model code.
+
+
+class PipelineState(TypedDict, total=False):
+    task: str
+    plan: Plan
+    step_outputs: list[str]
+    answer: str
+    review: Review
+
+
+def build_graph(board: Wright):
+    planner = board.planner()
+    worker = board.worker()
+    reviewer = board.reviewer()
+
+    def plan(state: PipelineState) -> dict:
+        result = planner.run_sync(f"Task: {state['task']}")
+        return {"plan": result.output}
+
+    def execute(state: PipelineState) -> dict:
+        outputs: list[str] = []
+        for i, step in enumerate(state["plan"].steps, start=1):
+            r = worker.run_sync(f"Task: {state['task']}\nStep {i}: {step}")
+            outputs.append(r.output)
+        return {"step_outputs": outputs, "answer": "\n\n".join(outputs)}
+
+    def review(state: PipelineState) -> dict:
+        r = reviewer.run_sync(f"Task: {state['task']}\n\nWork to review:\n{state['answer']}")
+        return {"review": r.output}
+
+    g = StateGraph(PipelineState)
+    g.add_node("plan", plan)  # cheap/local model
+    g.add_node("execute", execute)  # strong/remote model
+    g.add_node("review", review)  # cheap/local model
+    g.add_edge(START, "plan")
+    g.add_edge("plan", "execute")
+    g.add_edge("execute", "review")
+    g.add_edge("review", END)
+    return g.compile()

buildwright/models.yaml

@@ -0,0 +1,46 @@
+# Model registry: local and remote models in one place.
+# Agents never pick a model themselves: role -> id is defined in config
+# (BW_ROLE_* or the project's runtime.yaml)
+models:
+  # ---------------- local ----------------
+  - id: local/qwen3
+    label: Qwen3 8B (Ollama)
+    kind: local
+    base_url: http://localhost:11434/v1
+    model: qwen3:8b
+
+  - id: local/llamacpp
+    label: llama.cpp server (GGUF)
+    kind: local
+    base_url: http://localhost:8080/v1
+    model: local-model
+
+  # ---------------- remote ----------------
+  - id: remote/gpt-4o-mini
+    label: GPT-4o mini
+    kind: remote
+    base_url: https://api.openai.com/v1
+    model: gpt-4o-mini
+    api_key_env: OPENAI_API_KEY
+
+  - id: remote/gpt-4o
+    label: GPT-4o
+    kind: remote
+    base_url: https://api.openai.com/v1
+    model: gpt-4o
+    api_key_env: OPENAI_API_KEY
+
+  - id: remote/claude-sonnet
+    label: Claude Sonnet 4.5
+    kind: remote
+    base_url: https://api.anthropic.com/v1
+    model: claude-sonnet-4-5
+    api_key_env: ANTHROPIC_API_KEY
+
+  # --------- via LiteLLM proxy (optional, docker-compose) ---------
+  - id: litellm/gpt-4o-mini
+    label: GPT-4o mini via LiteLLM
+    kind: remote
+    base_url: http://localhost:4000/v1
+    model: gpt-4o-mini
+    api_key_env: LITELLM_API_KEY

buildwright/observability.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from .config import Settings
+
+
+class NullTracer:
+    """No-op: when Langfuse keys are absent — zero noise, zero active dependency."""
+
+    @contextmanager
+    def span(self, name: str, **meta: object) -> Iterator[None]:
+        yield
+
+
+class LangfuseTracer:
+    def __init__(self, settings: Settings) -> None:
+        from langfuse import Langfuse  # deferred import: only when actually used
+
+        self._client = Langfuse(
+            public_key=settings.langfuse_public_key,
+            secret_key=settings.langfuse_secret_key,
+            host=settings.langfuse_host,
+        )
+
+    @contextmanager
+    def span(self, name: str, **meta: object) -> Iterator[object]:
+        with self._client.start_as_current_observation(
+            name=name, metadata=dict(meta)
+        ) as span:
+            yield span
+
+
+def get_tracer(settings: Settings) -> NullTracer | LangfuseTracer:
+    if settings.langfuse_public_key and settings.langfuse_secret_key:
+        try:
+            return LangfuseTracer(settings)
+        except Exception:  # noqa: BLE001 - observability must never break a run
+            return NullTracer()
+    return NullTracer()

buildwright/registry.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel
+from pydantic_ai.models import Model
+from pydantic_ai.models.openai import OpenAIChatModel
+from pydantic_ai.providers.openai import OpenAIProvider
+
+
+class ModelSpec(BaseModel):
+    """An entry of models.yaml: a model reachable via an OpenAI-compatible endpoint."""
+
+    id: str
+    label: str
+    kind: Literal["local", "remote"]
+    base_url: str
+    model: str | None = None  # "wire" name; defaults to the id without the prefix
+    api_key_env: str | None = None
+    context_window: int | None = None
+
+
+class ModelRegistry:
+    def __init__(self, specs: list[ModelSpec]) -> None:
+        self._specs = {s.id: s for s in specs}
+
+    @classmethod
+    def load(cls, path: Path) -> ModelRegistry:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        specs = [ModelSpec.model_validate(s) for s in data.get("models", [])]
+        return cls(specs)
+
+    def spec(self, model_id: str) -> ModelSpec:
+        try:
+            return self._specs[model_id]
+        except KeyError:
+            known = ", ".join(sorted(self._specs))
+            raise KeyError(f"unknown model id '{model_id}'. Known ids: {known}") from None
+
+    def list(self, kind: str | None = None) -> list[ModelSpec]:
+        return [s for s in self._specs.values() if kind is None or s.kind == kind]
+
+    def build(self, model_id: str) -> Model:
+        """Build the PydanticAI model pointing at its endpoint. No network involved."""
+        s = self.spec(model_id)
+        api_key = "local"  # ollama/llama.cpp ignore it; the client requires non-empty
+        if s.api_key_env:
+            api_key = os.environ.get(s.api_key_env, "")
+            if not api_key:
+                raise RuntimeError(
+                    f"model '{s.id}' requires env var {s.api_key_env} (not set)"
+                )
+        return OpenAIChatModel(
+            s.model or s.id.split("/", 1)[1],
+            provider=OpenAIProvider(base_url=s.base_url, api_key=api_key),
+        )

buildwright-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: buildwright
+Version: 0.1.0
+Summary: Per-agent model routing for AI agents: LangGraph orchestration, PydanticAI agents, LiteLLM-ready registry, Langfuse tracing
+Project-URL: Homepage, https://github.com/jordimarsal/buildwright
+Project-URL: Repository, https://github.com/jordimarsal/buildwright
+Project-URL: Issues, https://github.com/jordimarsal/buildwright/issues
+Author: Jordi Marçal Poy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langfuse,langgraph,litellm,llm,model-routing,pydantic-ai,spec-driven-development
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: langfuse>=3.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: pydantic-ai-slim[openai]>=1.0
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# buildwright
+
+*The craftsman who builds per the spec* — one model per agent: mechanical steps
+go to the **local** model (cheap, fast), important decisions to the **remote**
+one (strong). The role→model mapping is configuration, not code — switching
+models touches zero lines of pipeline.
+
+## Install
+
+```bash
+uv tool install buildwright      # once published to PyPI
+# or for development:
+uv sync
+```
+
+## Division of roles (one tool, one job)
+
+| Piece | Role | Where it lives |
+|---|---|---|
+| **LangGraph** | the ORDER of the steps (graph, state, retries) | `graph.py` |
+| **PydanticAI** | EACH STEP (agent with structured output) | `agents.py` |
+| **LiteLLM** | WHO serves the model (optional proxy, fallbacks) | `litellm/config.yaml` |
+| **Langfuse** | WHETHER IT WORKED (traces, scores) | `observability.py` |
+
+## The pipeline
+
+```
+START → plan (local)  →  execute (remote)  →  review (local)  →  END
+        Plan struct.      final answer        Review struct.
+```
+
+Each node is a PydanticAI agent; the model is decided by the **role** in
+`Settings` (`BW_ROLE_*`), resolved against the `models.yaml` registry.
+
+## Quickstart
+
+```bash
+uv sync
+cp .env.example .env          # adjust BW_ROLE_* and keys
+
+uv run buildwright models     # list local and remote models
+uv run buildwright roles      # role -> model mapping
+uv run buildwright ask "write a snake game in python with pygame"
+```
+
+With no endpoints available, `ask` fails naming the exact model and the missing
+env var.
+
+## Local and remote models
+
+The whole registry speaks **OpenAI-compatible** (`models.yaml`):
+
+- **local/qwen3** → Ollama at `localhost:11434/v1`
+- **local/llamacpp** → `llama-server` at `localhost:8080/v1` (your GGUF)
+- **remote/gpt-4o-mini, gpt-4o** → OpenAI (key via `OPENAI_API_KEY`)
+- **remote/claude-sonnet** → Anthropic's OpenAI-compat layer
+- **litellm/*** → via the LiteLLM proxy (see `docker-compose.yml`)
+
+Registry resolution: `BW_MODELS_FILE` > project-local `./models.yaml` > the
+`models.yaml` bundled with the package. Adding a model = adding 5 lines.
+Reassigning one to an agent = changing a `BW_ROLE_*` in `.env`.
+
+## Optional full stack (LiteLLM + Langfuse + Ollama)
+
+With Docker, `docker compose up -d` brings up LiteLLM (routing/fallbacks),
+Langfuse (traces) and Ollama. Langfuse keys show up in its admin UI; copy them
+to `.env` and tracing turns itself on (without keys, the tracer is a no-op).
+
+## Publishing to PyPI
+
+Trusted publishing — no API tokens:
+
+1. Create `github.com/jordimarsal/buildwright` and push `main`.
+2. On pypi.org: *Add a pending publisher* → owner `jordimarsal`, repo
+   `buildwright`, workflow `release.yml`, environment `pypi`.
+3. `git tag v0.1.0 && git push --tags` → the workflow runs `uv build` and
+   publishes.
+
+## Tests
+
+```bash
+uv run pytest        # offline: pydantic-ai's TestModel, zero network
+```
+
+## Anti-mess rules
+
+1. Everything speaks OpenAI protocol; PydanticAI never imports litellm.
+2. One agent = one node = one job. No agents inside agents.
+3. Tracing registered exactly once (`observability.py`); never scattered.
+4. Offline evals in CI rule; Langfuse is production monitoring.
+5. Each piece joins when it has a real trigger (fallbacks→LiteLLM,
+   non-linear flow→LangGraph is already in).

buildwright-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+buildwright/__init__.py,sha256=AWzRjCUL2lAM4A7UJMXDUBT0c46zksXEuQVq2DlHnEc,98
+buildwright/agents.py,sha256=Nq-j27tpllObBR1NQeaK1Bn0K3K1zQ8JrEnkpKDbADM,2332
+buildwright/cli.py,sha256=xine3ba0OUlll4tXkWh2b9g3TFQ9WlJ_SssSEjz2bfo,2754
+buildwright/config.py,sha256=fqr-qFkg1hB9UqqMWvDOSEgT1HTAha5rLTXOT0ZRiC0,1522
+buildwright/graph.py,sha256=hQgleAy5nrIa7oCDhTmoXAon1KAi5_7Sb6PopR7cP6s,1612
+buildwright/models.yaml,sha256=gNsYK83cs8eRLp6dquJO44UtDKDDXWKt6jJJL5H875k,1270
+buildwright/observability.py,sha256=ZG8lRuENpu3PTwes1vhk1oIXCLE3_nZ20A-_nn1FPks,1259
+buildwright/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildwright/registry.py,sha256=FkazWd80pjpad79O96YgY9tas9GmALacDMMppdOj_vk,2091
+buildwright-0.1.0.dist-info/METADATA,sha256=yJE4rSPw5lpMb-MApD1RS9XYMLBa3RO9wMniZbhy9NM,4479
+buildwright-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+buildwright-0.1.0.dist-info/entry_points.txt,sha256=izS4KVdhp6UAp5XCmA9M0QA8JKIkNAaCgFDzH0_7IpA,53
+buildwright-0.1.0.dist-info/licenses/LICENSE,sha256=eMgpubNpl0LA4mylx__ss8lgutn16acZxLGnuGclGuE,1074
+buildwright-0.1.0.dist-info/RECORD,,

buildwright-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

buildwright-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+buildwright = buildwright.cli:main

buildwright-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordi Marçal Poy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.