crewforge 0.1.0__py3-none-any.whl

crewforge/__init__.py

@@ -0,0 +1,3 @@
+"""crewforge — one crew of LLM agents, four recipes, any OpenAI-compatible provider."""
+
+__version__ = "0.1.0"

crewforge/__main__.py

@@ -0,0 +1,4 @@
+from crewforge.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

crewforge/cli.py

@@ -0,0 +1,128 @@
+"""``crewforge`` command line: global provider options + the four recipes."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import click
+from rich.table import Table
+
+from . import __version__
+from .cli_support import EXIT_USAGE, console, err_console, fail
+from .core.config import LLMConfig, Settings
+from .core.errors import ConfigError
+from .core.providers import ENV_API_KEY, PROVIDERS
+from .recipes.api.cli import commands as api_commands
+from .recipes.content.cli import commands as content_commands
+from .recipes.docs.cli import commands as docs_commands
+from .recipes.review.cli import commands as review_commands
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="crewforge")
+@click.option(
+    "--provider",
+    "-P",
+    default=None,
+    help="Provider preset (see `crewforge providers`). Env: CREWFORGE_PROVIDER. Default: openai.",
+)
+@click.option("--model", "-m", default=None, help="Model name. Env: CREWFORGE_MODEL.")
+@click.option(
+    "--base-url", default=None, help="OpenAI-compatible base URL. Env: CREWFORGE_BASE_URL."
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="crewforge.yaml (written by `crewforge init`); ${VAR} references are expanded.",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Log HTTP retries and agent progress.")
+@click.pass_context
+def main(ctx, provider, model, base_url, config_path, verbose):
+    """One crew of LLM agents, four recipes, any OpenAI-compatible provider.
+
+    \b
+    Recipes:
+      review     multi-agent code review
+      ingest     parse + chunk documents (no LLM calls)
+      ask        document Q&A with citations (+ --verify fact-check)
+      summarize  document summaries
+      scaffold   natural language -> FastAPI project + OpenAPI spec
+      validate   check an OpenAPI spec (and a scaffolded app) offline
+      write      research -> outline -> write -> SEO -> edit -> quality -> publish
+
+    API keys are read from the environment only (e.g. OPENAI_API_KEY) and are
+    never written to disk. Exit codes: 0 ok, 1 run failed, 2 usage/config error.
+    """
+    logging.basicConfig(
+        level=logging.INFO if verbose else logging.WARNING, format="%(levelname)s %(message)s"
+    )
+    try:
+        settings = Settings.from_yaml(config_path) if config_path else Settings()
+    except ConfigError as exc:
+        fail(f"configuration: {exc}", EXIT_USAGE)
+    overrides = {
+        k: v for k, v in {"provider": provider, "model": model, "base_url": base_url}.items() if v
+    }
+    if overrides:
+        data = settings.llm.model_dump()
+        if "provider" in overrides and overrides["provider"] != settings.llm.provider:
+            # A different provider means different defaults: re-resolve from scratch,
+            # keeping only explicitly given values.
+            reset = ("api_key", "base_url", "model", "auth_style")
+            data = {k: v for k, v in data.items() if k not in reset}
+        data.update(overrides)
+        settings.llm = LLMConfig(**data)
+    ctx.ensure_object(dict)
+    ctx.obj["settings"] = settings
+
+
+@main.command()
+def providers():
+    """List provider presets and the env var that holds each key."""
+    table = Table(title="Provider presets", title_justify="left")
+    for title in ("Name", "Provider", "Base URL", "Default model", "Key env var", "Auth"):
+        table.add_column(title, overflow="fold", style="bold cyan" if title == "Name" else None)
+    for p in PROVIDERS.values():
+        table.add_row(
+            p.name,
+            p.label,
+            p.base_url or "(set CREWFORGE_BASE_URL / --base-url)",
+            p.default_model or "(set CREWFORGE_MODEL / --model)",
+            p.env_key + (" (optional)" if p.keyless else ""),
+            "api-key header" if p.auth_style == "api-key" else "Bearer",
+        )
+    console.print(table)
+    console.print(
+        f"Any preset's key, URL and model can be overridden with {ENV_API_KEY}, "
+        "CREWFORGE_BASE_URL and CREWFORGE_MODEL."
+    )
+
+
+@main.command()
+@click.option(
+    "--output", "-o", default="crewforge.yaml", show_default=True, type=click.Path(dir_okay=False)
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing file.")
+@click.pass_context
+def init(ctx, output, force):
+    """Write a starter crewforge.yaml (the key is written as a ${VAR} reference)."""
+    path = Path(output)
+    if path.exists() and not force:
+        fail(f"{path} already exists (use --force to overwrite)", EXIT_USAGE)
+    settings: Settings = ctx.obj["settings"]
+    settings.write_template(path)
+    err_console.print(
+        f"[green]Wrote {path}[/] — api_key is the reference "
+        f"${{{settings.llm.key_env_var}}}; export that variable, never paste the key into the file."
+    )
+
+
+for _cmd in (*review_commands, *docs_commands, *api_commands, *content_commands):
+    main.add_command(_cmd)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

crewforge/cli_support.py

@@ -0,0 +1,109 @@
+"""Helpers shared by every recipe's CLI commands.
+
+Exit codes (stable, documented in the README):
+
+* 0 — the run succeeded
+* 1 — the run failed: an agent errored, returned empty/unparseable output, a
+  validator found problems, or the LLM endpoint refused the request
+* 2 — usage or configuration error (bad flags, unknown provider, missing key)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import Coroutine
+from typing import Any, NoReturn, TypeVar
+
+import click
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from .core.config import LLMConfig, Settings
+from .core.errors import AgentError, ConfigError, CrewFailedError, LLMError
+from .core.usage import UsageTracker
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_USAGE = 2
+
+T = TypeVar("T")
+
+console = Console()
+# Status, warnings and errors go to stderr so JSON on stdout stays parseable.
+err_console = Console(stderr=True)
+
+
+def settings_from_ctx(ctx: click.Context) -> Settings:
+    obj = ctx.find_root().obj or {}
+    settings = obj.get("settings")
+    if settings is None:
+        settings = Settings()
+        obj["settings"] = settings
+    return settings
+
+
+def llm_config(ctx: click.Context) -> LLMConfig:
+    return settings_from_ctx(ctx).llm
+
+
+def recipe_settings(ctx: click.Context, recipe: str) -> dict[str, Any]:
+    return dict(getattr(settings_from_ctx(ctx), recipe, {}) or {})
+
+
+def fail(message: str, code: int = EXIT_FAILED) -> NoReturn:
+    err_console.print(f"[bold red]error:[/] {escape(message)}", highlight=False, soft_wrap=True)
+    sys.exit(code)
+
+
+def report_crew_failure(exc: CrewFailedError) -> None:
+    err_console.print(f"[bold red]error:[/] {exc.crew} failed", highlight=False, soft_wrap=True)
+    for f in exc.failures:
+        err_console.print(
+            f"  [red]✗ agent '{escape(f.agent)}'[/] ({f.kind}): {escape(f.error)}",
+            highlight=False,
+            soft_wrap=True,
+        )
+
+
+def run(coro: Coroutine[Any, Any, T]) -> T:
+    """Run a recipe coroutine and translate failures into exit codes and messages."""
+    try:
+        return asyncio.run(coro)
+    except ConfigError as exc:
+        fail(f"configuration: {exc}", EXIT_USAGE)
+    except CrewFailedError as exc:
+        report_crew_failure(exc)
+        sys.exit(EXIT_FAILED)
+    except AgentError as exc:
+        fail(str(exc))
+    except LLMError as exc:
+        fail(f"LLM request failed: {exc}")
+
+
+def print_usage(tracker: UsageTracker, *, title: str = "Token usage (provider-reported)") -> None:
+    """Per-agent usage table on stderr. Numbers come only from provider responses."""
+    agents = tracker.by_agent()
+    if not agents:
+        return
+    table = Table(title=title, title_justify="left")
+    table.add_column("Agent", style="cyan")
+    table.add_column("Calls", justify="right")
+    table.add_column("Prompt", justify="right")
+    table.add_column("Completion", justify="right")
+    table.add_column("Total", justify="right", style="green")
+    for name, a in agents.items():
+        total = f"{a.total_tokens:,}"
+        if a.unreported_calls:
+            total += f" (+{a.unreported_calls} unreported)"
+        table.add_row(name, str(a.calls), f"{a.prompt_tokens:,}", f"{a.completion_tokens:,}", total)
+    table.add_row(
+        "[bold]total[/]", str(tracker.total_calls), "", "", f"[bold]{tracker.total_tokens:,}[/]"
+    )
+    err_console.print(table)
+    if tracker.unreported_calls:
+        err_console.print(
+            f"[yellow]{tracker.unreported_calls} call(s) returned no usage; "
+            "they are not counted (nothing is estimated).[/]"
+        )

crewforge/core/__init__.py

@@ -0,0 +1,54 @@
+"""Reusable core: providers, config, client, agents, crews, parsing, usage, errors."""
+
+from .agent import Agent
+from .client import ChatResponse, LLMClient, Message, Usage, is_retryable_status
+from .config import LLMConfig, Settings, expand_env
+from .crew import Crew, is_empty
+from .errors import (
+    AgentError,
+    AgentFailure,
+    ConfigError,
+    CrewFailedError,
+    CrewForgeError,
+    EmptyOutputError,
+    LLMError,
+    LLMHTTPError,
+    LLMResponseError,
+    OutputParseError,
+)
+from .parsing import extract_code_block, extract_json, parse_json
+from .providers import DEFAULT_PROVIDER, PROVIDERS, Provider, get_provider
+from .usage import AgentUsage, UsageTracker
+
+__all__ = [
+    "DEFAULT_PROVIDER",
+    "PROVIDERS",
+    "Agent",
+    "AgentError",
+    "AgentFailure",
+    "AgentUsage",
+    "ChatResponse",
+    "ConfigError",
+    "Crew",
+    "CrewFailedError",
+    "CrewForgeError",
+    "EmptyOutputError",
+    "LLMClient",
+    "LLMConfig",
+    "LLMError",
+    "LLMHTTPError",
+    "LLMResponseError",
+    "Message",
+    "OutputParseError",
+    "Provider",
+    "Settings",
+    "Usage",
+    "UsageTracker",
+    "expand_env",
+    "extract_code_block",
+    "extract_json",
+    "get_provider",
+    "is_empty",
+    "is_retryable_status",
+    "parse_json",
+]

crewforge/core/agent.py

@@ -0,0 +1,118 @@
+"""The :class:`Agent` base class: one role, one system prompt, one LLM call at a time."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, ClassVar
+
+from .client import ChatResponse, LLMClient, Message
+from .errors import EmptyOutputError
+from .parsing import M, parse_json
+from .usage import UsageTracker
+
+
+class Agent:
+    """Base class for every agent in every recipe.
+
+    Subclasses set :attr:`name`, :attr:`description` and :attr:`system_prompt`
+    and implement their task with :meth:`ask` / :meth:`ask_json`. Both record
+    provider-reported usage and refuse to return empty or unparseable output:
+    that refusal is what lets a crew fail honestly instead of reporting success.
+    """
+
+    name: ClassVar[str] = "agent"
+    description: ClassVar[str] = ""
+    system_prompt: ClassVar[str] = "You are a precise, factual assistant."
+    #: Per-agent sampling defaults; ``None`` means "use the LLMConfig value".
+    temperature: ClassVar[float | None] = None
+    max_tokens: ClassVar[int | None] = None
+
+    def __init__(
+        self,
+        client: LLMClient,
+        tracker: UsageTracker | None = None,
+        *,
+        system_prompt: str | None = None,
+        model: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> None:
+        self.client = client
+        self.tracker = tracker if tracker is not None else UsageTracker()
+        self._system_prompt = system_prompt
+        self._model = model
+        self._temperature = temperature if temperature is not None else self.temperature
+        self._max_tokens = max_tokens if max_tokens is not None else self.max_tokens
+
+    @property
+    def effective_system_prompt(self) -> str:
+        return self._system_prompt or self.system_prompt
+
+    def build_messages(
+        self, prompt: str, *, system: str | None = None, context: str | None = None
+    ) -> list[Message]:
+        messages = [Message("system", system or self.effective_system_prompt)]
+        if context:
+            messages.append(Message("user", f"Context:\n{context}"))
+        messages.append(Message("user", prompt))
+        return messages
+
+    async def ask(
+        self,
+        prompt: str,
+        *,
+        system: str | None = None,
+        context: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        allow_empty: bool = False,
+    ) -> ChatResponse:
+        """Send one prompt; return the response or raise naming this agent."""
+        messages = self.build_messages(prompt, system=system, context=context)
+        start = time.monotonic()
+        try:
+            response = await self.client.chat(
+                messages,
+                model=self._model,
+                temperature=temperature if temperature is not None else self._temperature,
+                max_tokens=max_tokens if max_tokens is not None else self._max_tokens,
+            )
+        except Exception:
+            self.tracker.record(self.name, None, (time.monotonic() - start) * 1000, error=True)
+            raise
+        self.tracker.record(
+            self.name,
+            response.usage,
+            (time.monotonic() - start) * 1000,
+            retries=max(0, response.attempts - 1),
+        )
+        # Honest-failure guard: a blank completion is a failure of this agent,
+        # never an answer. Removing this check makes tests/core/test_honest_failure.py red.
+        if not allow_empty and not response.content.strip():
+            detail = f"finish_reason={response.finish_reason}" if response.finish_reason else ""
+            raise EmptyOutputError(self.name, detail)
+        return response
+
+    async def ask_json(
+        self,
+        prompt: str,
+        *,
+        schema: type[M] | None = None,
+        expect: type | tuple[type, ...] = dict,
+        system: str | None = None,
+        context: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> Any:
+        """Like :meth:`ask` but the reply must parse as JSON (and match ``schema``)."""
+        response = await self.ask(
+            prompt,
+            system=system,
+            context=context,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return parse_json(response.content, agent=self.name, expect=expect, schema=schema)
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} name={self.name!r}>"

crewforge/core/client.py

@@ -0,0 +1,253 @@
+"""One async client for every OpenAI-compatible ``/chat/completions`` endpoint.
+
+Policy, in one place:
+
+* Non-streaming: ``"stream": false`` is always sent. Some compatible servers
+  stream when the flag is omitted, which used to make every agent parse an
+  SSE body as nothing and "succeed" with empty output.
+* Retries: only HTTP 429, HTTP 5xx and network/timeout errors are retried,
+  with bounded exponential backoff (``Retry-After`` honoured up to
+  ``max_retry_delay``). 401/403 and every other 4xx fail on the first attempt.
+* Usage: token counts come only from the provider's ``usage`` object. When a
+  provider omits it, :attr:`Usage.reported` is ``False`` and the counts stay
+  zero; nothing is estimated.
+* Secrets: the key lives in request headers only. It is never logged and never
+  part of an error message.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from .config import LLMConfig
+from .errors import LLMError, LLMHTTPError, LLMResponseError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Message:
+    role: str
+    content: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"role": self.role, "content": self.content}
+
+
+@dataclass
+class Usage:
+    """Token usage exactly as the provider reported it."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    cached_tokens: int = 0
+    reported: bool = False  # False = provider sent no usage object
+
+    @classmethod
+    def from_payload(cls, data: Any) -> Usage:
+        if not isinstance(data, dict):
+            return cls()
+        prompt = _as_int(data.get("prompt_tokens"))
+        completion = _as_int(data.get("completion_tokens"))
+        total = _as_int(data.get("total_tokens")) or prompt + completion
+        details = data.get("prompt_tokens_details") or {}
+        cached = _as_int(details.get("cached_tokens")) if isinstance(details, dict) else 0
+        return cls(prompt, completion, total, cached, reported=True)
+
+    def add(self, other: Usage) -> None:
+        self.prompt_tokens += other.prompt_tokens
+        self.completion_tokens += other.completion_tokens
+        self.total_tokens += other.total_tokens
+        self.cached_tokens += other.cached_tokens
+        self.reported = self.reported or other.reported
+
+
+def _as_int(value: Any) -> int:
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+@dataclass
+class ChatResponse:
+    content: str
+    usage: Usage = field(default_factory=Usage)
+    model: str = ""
+    finish_reason: str = ""
+    reasoning: str = ""
+    latency_ms: float = 0.0
+    attempts: int = 1
+
+
+MessageLike = Message | dict[str, str]
+
+
+def is_retryable_status(status: int) -> bool:
+    """429 and 5xx are transient; every other status is a caller/config problem."""
+    return status == 429 or status >= 500
+
+
+class LLMClient:
+    """Async OpenAI-compatible chat client with a strict retry policy.
+
+    Use as an async context manager, or call :meth:`aclose` when done. A
+    ``transport`` can be injected (``httpx.MockTransport``) for tests.
+    """
+
+    def __init__(
+        self,
+        config: LLMConfig,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        self.config = config
+        self._transport = transport
+        self._sleep = sleep
+        self._http: httpx.AsyncClient | None = None
+        self.total_usage = Usage()
+        self.request_count = 0
+
+    async def __aenter__(self) -> LLMClient:
+        self._ensure_http()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    def _ensure_http(self) -> httpx.AsyncClient:
+        if self._http is None or self._http.is_closed:
+            self._http = httpx.AsyncClient(
+                base_url=self.config.base_url,
+                headers=self.config.headers,
+                timeout=httpx.Timeout(self.config.timeout),
+                transport=self._transport,
+            )
+        return self._http
+
+    async def aclose(self) -> None:
+        if self._http is not None and not self._http.is_closed:
+            await self._http.aclose()
+
+    def _backoff(self, attempt: int, response: httpx.Response | None) -> float:
+        delay = self.config.retry_delay * (2 ** (attempt - 1))
+        if response is not None:
+            retry_after = response.headers.get("retry-after", "")
+            try:
+                delay = max(delay, float(retry_after))
+            except ValueError:
+                pass
+        return min(delay, self.config.max_retry_delay)
+
+    async def chat(
+        self,
+        messages: Sequence[MessageLike],
+        *,
+        model: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> ChatResponse:
+        payload: dict[str, Any] = {
+            "model": model or self.config.model,
+            "messages": [m.to_dict() if isinstance(m, Message) else dict(m) for m in messages],
+            # ``is not None``: an explicit temperature of 0 must be sent as 0.
+            "temperature": self.config.temperature if temperature is None else temperature,
+            "max_tokens": self.config.max_tokens if max_tokens is None else max_tokens,
+            "stream": False,
+        }
+        if extra:
+            payload.update(extra)
+            payload["stream"] = False
+
+        http = self._ensure_http()
+        attempts = max(1, self.config.max_retries)
+        start = time.monotonic()
+        last_exc: Exception | None = None
+        for attempt in range(1, attempts + 1):
+            response: httpx.Response | None = None
+            try:
+                response = await http.post("/chat/completions", json=payload)
+            except httpx.TransportError as exc:  # connect/read errors and timeouts
+                last_exc = exc
+                if attempt < attempts:
+                    logger.warning("LLM request failed (%s); retry %d", type(exc).__name__, attempt)
+                    await self._sleep(self._backoff(attempt, None))
+                    continue
+                raise LLMError(
+                    f"cannot reach {self.config.base_url} after {attempt} attempt(s): "
+                    f"{type(exc).__name__}: {exc}"
+                ) from exc
+
+            if response.status_code >= 400:
+                if is_retryable_status(response.status_code) and attempt < attempts:
+                    logger.warning("LLM HTTP %s; retry %d", response.status_code, attempt)
+                    await self._sleep(self._backoff(attempt, response))
+                    continue
+                raise LLMHTTPError(
+                    response.status_code,
+                    self._http_error_message(response, attempt),
+                    attempts=attempt,
+                )
+            return self._parse(response, start, attempt)
+        raise LLMError(f"request failed: {last_exc}")  # pragma: no cover - loop always returns
+
+    def _http_error_message(self, response: httpx.Response, attempts: int) -> str:
+        detail = ""
+        try:
+            body = response.json()
+            err = body.get("error") if isinstance(body, dict) else None
+            if isinstance(err, dict):
+                detail = str(err.get("message") or err.get("code") or "")
+            elif err:
+                detail = str(err)
+            elif isinstance(body, dict):
+                detail = str(body.get("message") or body.get("detail") or "")
+        except ValueError:
+            detail = response.text
+        detail = " ".join(detail.split())[:300]
+        msg = f"HTTP {response.status_code} from {self.config.base_url}"
+        if response.status_code in (401, 403):
+            msg += f" (authentication failed — check {self.config.key_env_var})"
+        elif response.status_code == 404:
+            msg += f" (check the base URL and that model '{self.config.model}' exists)"
+        if attempts > 1:
+            msg += f" after {attempts} attempts"
+        if detail:
+            msg += f": {detail}"
+        return msg
+
+    def _parse(self, response: httpx.Response, start: float, attempts: int) -> ChatResponse:
+        try:
+            data = response.json()
+        except ValueError as exc:
+            snippet = " ".join(response.text.split())[:120]
+            raise LLMResponseError(
+                f"endpoint returned non-JSON body (is it streaming?): {snippet!r}"
+            ) from exc
+        choices = data.get("choices") if isinstance(data, dict) else None
+        if not choices or not isinstance(choices, list) or not isinstance(choices[0], dict):
+            raise LLMResponseError(f"response has no choices: {str(data)[:160]!r}")
+        choice = choices[0]
+        message = choice.get("message") or {}
+        usage = Usage.from_payload(data.get("usage"))
+        self.total_usage.add(usage)
+        self.request_count += 1
+        return ChatResponse(
+            content=message.get("content") or "",
+            usage=usage,
+            model=data.get("model") or "",
+            finish_reason=choice.get("finish_reason") or "",
+            reasoning=message.get("reasoning_content") or message.get("reasoning") or "",
+            latency_ms=round((time.monotonic() - start) * 1000, 1),
+            attempts=attempts,
+        )