crewforge 0.1.0__py3-none-any.whl

crewforge/core/config.py

@@ -0,0 +1,181 @@
+"""LLM connection settings and the optional ``crewforge.yaml`` file.
+
+Resolution order for each connection field (first non-empty wins):
+
+1. an explicit value (constructor argument, CLI flag or YAML file)
+2. the generic ``CREWFORGE_API_KEY`` / ``CREWFORGE_BASE_URL`` / ``CREWFORGE_MODEL``
+3. the provider's own variables, e.g. ``OPENAI_API_KEY`` / ``OPENAI_BASE_URL``
+4. the preset default
+
+Secrets are only ever read from the environment (or from a YAML ``${VAR}``
+reference that is expanded at load time). Nothing in this module writes a key
+to disk: :meth:`Settings.to_template` emits ``${VAR}`` references instead.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .errors import ConfigError
+from .providers import (
+    DEFAULT_PROVIDER,
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    ENV_MODEL,
+    ENV_PROVIDER,
+    PROVIDERS,
+    get_provider,
+)
+
+_ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def expand_env(value: Any) -> Any:
+    """Recursively expand ``${VAR}`` references from the environment.
+
+    An unset variable expands to an empty string, so a missing key is reported
+    by :meth:`LLMConfig.validate` instead of being sent literally as the key.
+    """
+    if isinstance(value, str):
+        return _ENV_REF.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [expand_env(v) for v in value]
+    return value
+
+
+class LLMConfig(BaseModel):
+    """Connection settings for one OpenAI-compatible chat completions endpoint."""
+
+    model_config = ConfigDict(validate_assignment=False)
+
+    provider: str = ""
+    # repr=False keeps the key out of logs, tracebacks and ``print(config)``.
+    api_key: str = Field(default="", repr=False)
+    base_url: str = ""
+    model: str = ""
+    auth_style: str = ""  # "bearer" | "api-key"; blank = provider default
+    temperature: float = 0.3
+    max_tokens: int = 4096
+    timeout: float = 120.0  # seconds, per HTTP attempt
+    max_retries: int = 3  # total attempts for 429 / 5xx / network errors
+    retry_delay: float = 1.0  # base delay for exponential backoff (seconds)
+    max_retry_delay: float = 30.0
+
+    @model_validator(mode="after")
+    def _resolve(self) -> LLMConfig:
+        self.provider = (self.provider or os.environ.get(ENV_PROVIDER) or DEFAULT_PROVIDER).lower()
+        preset = get_provider(self.provider)
+        env_key = preset.env_key if preset else ENV_API_KEY
+        env_base = preset.env_base if preset else ENV_BASE_URL
+        if not self.api_key:
+            self.api_key = os.environ.get(ENV_API_KEY) or os.environ.get(env_key, "")
+        if not self.base_url:
+            self.base_url = (
+                os.environ.get(ENV_BASE_URL)
+                or os.environ.get(env_base)
+                or (preset.base_url if preset else "")
+            )
+        self.base_url = self.base_url.rstrip("/")
+        if not self.model:
+            self.model = os.environ.get(ENV_MODEL) or (preset.default_model if preset else "")
+        if not self.auth_style:
+            self.auth_style = preset.auth_style if preset else "bearer"
+        return self
+
+    @property
+    def preset(self):
+        return get_provider(self.provider)
+
+    @property
+    def key_env_var(self) -> str:
+        """The variable a user should set to provide the key for this provider."""
+        preset = self.preset
+        return preset.env_key if preset else ENV_API_KEY
+
+    @property
+    def headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            if self.auth_style == "api-key":
+                headers["api-key"] = self.api_key
+            else:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def validate_config(self) -> list[str]:
+        """Return human-readable problems; empty list means the config can run."""
+        problems: list[str] = []
+        preset = self.preset
+        if preset is None:
+            problems.append(
+                f"unknown provider '{self.provider}'. Known: {', '.join(PROVIDERS)} "
+                "(use 'custom' with --base-url for any other OpenAI-compatible server)"
+            )
+        if not self.base_url:
+            problems.append(f"no base URL: set {ENV_BASE_URL} or pass --base-url")
+        if not self.model:
+            problems.append(f"no model: set {ENV_MODEL} or pass --model")
+        if not self.api_key and not (preset and preset.keyless):
+            problems.append(f"no API key: set {self.key_env_var} (or {ENV_API_KEY})")
+        if self.auth_style not in ("bearer", "api-key"):
+            problems.append(f"auth_style must be 'bearer' or 'api-key', not '{self.auth_style}'")
+        if self.max_retries < 1:
+            problems.append("max_retries must be >= 1 (it counts total attempts)")
+        if self.timeout <= 0:
+            problems.append("timeout must be > 0 seconds")
+        return problems
+
+    def require_valid(self) -> LLMConfig:
+        """Raise :class:`ConfigError` listing every problem, or return ``self``."""
+        problems = self.validate_config()
+        if problems:
+            raise ConfigError("; ".join(problems))
+        return self
+
+    def public_dict(self) -> dict[str, Any]:
+        """Settings safe to print or save: the key is replaced by its env reference."""
+        data = self.model_dump()
+        data["api_key"] = "${" + self.key_env_var + "}"
+        return data
+
+
+class Settings(BaseModel):
+    """Root of ``crewforge.yaml``: one ``llm`` block plus per-recipe sections."""
+
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    review: dict[str, Any] = Field(default_factory=dict)
+    docs: dict[str, Any] = Field(default_factory=dict)
+    api: dict[str, Any] = Field(default_factory=dict)
+    content: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> Settings:
+        try:
+            data = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+        except (OSError, yaml.YAMLError) as exc:
+            raise ConfigError(f"cannot read config {path}: {exc}") from exc
+        if not isinstance(data, dict):
+            raise ConfigError(f"config {path} must be a mapping at the top level")
+        return cls(**expand_env(data))
+
+    def to_template(self) -> dict[str, Any]:
+        """Dict safe to write to disk: secrets are ``${VAR}`` references, never values."""
+        data = self.model_dump()
+        data["llm"] = self.llm.public_dict()
+        return data
+
+    def write_template(self, path: str | Path) -> Path:
+        out = Path(path)
+        out.write_text(
+            yaml.safe_dump(self.to_template(), sort_keys=False, allow_unicode=True),
+            encoding="utf-8",
+        )
+        return out

crewforge/core/crew.py

@@ -0,0 +1,144 @@
+"""A :class:`Crew` runs agents in sequential steps and parallel stages.
+
+The crew owns the shared client and usage tracker, and it is where honest
+failure is enforced for a whole run: a step whose agent raised, returned
+nothing, or returned unparseable output stops the run with
+:class:`CrewFailedError` naming the agent(s). Recipes never decide on their own
+that a half-empty run is a success.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Mapping
+from typing import Any, Literal, TypeVar
+
+import httpx
+
+from .agent import Agent
+from .client import LLMClient
+from .config import LLMConfig
+from .errors import AgentFailure, ConfigError, CrewFailedError, EmptyOutputError, classify
+from .usage import UsageTracker
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+A = TypeVar("A", bound=Agent)
+
+
+def is_empty(value: Any) -> bool:
+    """``None``, blank strings and empty containers count as "returned nothing"."""
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return not value.strip()
+    if isinstance(value, (list, tuple, dict, set, frozenset)):
+        return len(value) == 0
+    return False
+
+
+class Crew:
+    """Shared client + tracker + failure bookkeeping for one run of a recipe."""
+
+    def __init__(
+        self,
+        name: str,
+        config: LLMConfig,
+        *,
+        client: LLMClient | None = None,
+        tracker: UsageTracker | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        validate: bool = True,
+    ) -> None:
+        if validate and client is None:
+            config.require_valid()
+        self.name = name
+        self.config = config
+        self._owns_client = client is None
+        self.client = client if client is not None else LLMClient(config, transport=transport)
+        self.tracker = tracker if tracker is not None else UsageTracker()
+        self.failures: list[AgentFailure] = []
+
+    async def __aenter__(self) -> Crew:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        self.tracker.finish()
+        if self._owns_client:
+            await self.client.aclose()
+
+    def agent(self, cls: type[A], **kwargs: Any) -> A:
+        """Instantiate an agent bound to this crew's client and tracker."""
+        return cls(self.client, self.tracker, **kwargs)
+
+    def _fail(self, agent: str, exc: BaseException) -> AgentFailure:
+        failure = AgentFailure(
+            agent=agent, error=str(exc) or type(exc).__name__, kind=classify(exc)
+        )
+        self.failures.append(failure)
+        logger.info("[%s] agent %r failed: %s", self.name, agent, failure.error)
+        return failure
+
+    @staticmethod
+    def _checked(agent: str, value: T, allow_empty: bool) -> T:
+        # Second honest-failure guard: even if an agent's own code swallowed an
+        # error and returned a default, "nothing" is never a successful result.
+        if not allow_empty and is_empty(value):
+            raise EmptyOutputError(agent, "result was empty")
+        return value
+
+    async def step(self, agent: str | Agent, work: Awaitable[T], *, allow_empty: bool = False) -> T:
+        """Run one required step; raise :class:`CrewFailedError` if it fails."""
+        name = agent.name if isinstance(agent, Agent) else agent
+        try:
+            return self._checked(name, await work, allow_empty)
+        except ConfigError:
+            raise
+        except Exception as exc:
+            raise CrewFailedError(self.name, [self._fail(name, exc)]) from exc
+
+    async def parallel(
+        self,
+        work: Mapping[str, Awaitable[Any]],
+        *,
+        require: Literal["all", "any"] = "all",
+        allow_empty: bool = False,
+    ) -> dict[str, Any]:
+        """Run several agents concurrently.
+
+        ``require="all"`` (default): any failure fails the run, naming every
+        failed agent. ``require="any"``: failures are recorded in
+        :attr:`failures` and the successful results are returned, unless none
+        succeeded.
+        """
+        names = list(work)
+        outcomes = await asyncio.gather(*work.values(), return_exceptions=True)
+        results: dict[str, Any] = {}
+        failed: list[AgentFailure] = []
+        for name, outcome in zip(names, outcomes, strict=True):
+            if isinstance(outcome, ConfigError):
+                raise outcome
+            if isinstance(outcome, BaseException):
+                if not isinstance(outcome, Exception):
+                    raise outcome  # CancelledError, KeyboardInterrupt: never swallow
+                failed.append(self._fail(name, outcome))
+                continue
+            try:
+                results[name] = self._checked(name, outcome, allow_empty)
+            except EmptyOutputError as exc:
+                failed.append(self._fail(name, exc))
+        if failed and (require == "all" or not results):
+            raise CrewFailedError(self.name, failed)
+        return results
+
+    def report(self) -> dict[str, Any]:
+        return {
+            "crew": self.name,
+            "status": "partial" if self.failures else "success",
+            "failures": [
+                {"agent": f.agent, "kind": f.kind, "error": f.error} for f in self.failures
+            ],
+            "usage": self.tracker.summary(),
+        }

crewforge/core/errors.py

@@ -0,0 +1,106 @@
+"""Exception hierarchy.
+
+Every failure a user can hit maps to one of these, and every agent-level
+failure carries the agent's name so the CLI can say exactly *who* failed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class CrewForgeError(Exception):
+    """Base class for all crewforge errors."""
+
+
+class ConfigError(CrewForgeError):
+    """The configuration cannot work (unknown provider, missing key or URL, ...)."""
+
+
+class LLMError(CrewForgeError):
+    """The LLM endpoint could not produce a usable response."""
+
+
+class LLMHTTPError(LLMError):
+    """The endpoint answered with a non-2xx status after any allowed retries."""
+
+    def __init__(self, status_code: int, message: str, *, attempts: int = 1) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.attempts = attempts
+
+
+class LLMResponseError(LLMError):
+    """The endpoint answered 2xx but the body is not a chat completion."""
+
+
+class AgentError(CrewForgeError):
+    """An agent produced output that cannot be used. Always names the agent."""
+
+    def __init__(self, agent: str, reason: str) -> None:
+        super().__init__(f"agent '{agent}' {reason}")
+        self.agent = agent
+        self.reason = reason
+
+
+class EmptyOutputError(AgentError):
+    """The model returned no content (blank, whitespace or null)."""
+
+    def __init__(self, agent: str, detail: str = "") -> None:
+        reason = "returned empty output"
+        if detail:
+            reason += f" ({detail})"
+        super().__init__(agent, reason)
+
+
+class OutputParseError(AgentError):
+    """The model returned content, but not in the structure the agent requires."""
+
+    def __init__(self, agent: str, detail: str, excerpt: str = "") -> None:
+        reason = f"returned unparseable output: {detail}"
+        if excerpt:
+            reason += f" — got: {excerpt!r}"
+        super().__init__(agent, reason)
+        self.excerpt = excerpt
+
+
+@dataclass(frozen=True)
+class AgentFailure:
+    """One agent that failed inside a crew run."""
+
+    agent: str
+    error: str
+    kind: str = "error"  # empty | parse | http | error
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return f"{self.agent}: {self.error}"
+
+
+class CrewFailedError(CrewForgeError):
+    """A crew run cannot honestly report success.
+
+    Raised when a required agent failed, returned nothing, or returned output
+    that could not be parsed. ``failures`` names every agent involved.
+    """
+
+    def __init__(self, crew: str, failures: list[AgentFailure]) -> None:
+        self.crew = crew
+        self.failures = list(failures)
+        names = ", ".join(f"'{f.agent}'" for f in self.failures) or "(none)"
+        detail = "; ".join(f"{f.agent}: {f.error}" for f in self.failures)
+        super().__init__(f"{crew} failed — agent(s) {names}: {detail}")
+
+    @property
+    def agents(self) -> list[str]:
+        return [f.agent for f in self.failures]
+
+
+def classify(exc: BaseException) -> str:
+    """Short machine-readable kind for an exception (used in reports/JSON)."""
+    if isinstance(exc, EmptyOutputError):
+        return "empty"
+    if isinstance(exc, OutputParseError):
+        return "parse"
+    if isinstance(exc, LLMHTTPError):
+        return "http"
+    return "error"

crewforge/core/parsing.py

@@ -0,0 +1,110 @@
+"""Structured-output parsing for LLM replies.
+
+Real models wrap JSON in Markdown fences, add a sentence before it, or answer
+with prose. :func:`extract_json` tolerates the first two; :func:`parse_json`
+turns the third into an :class:`OutputParseError` that names the agent instead
+of letting a default value slip through as if it were an answer.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from .errors import EmptyOutputError, OutputParseError
+
+_FENCE = re.compile(r"```[ \t]*([A-Za-z0-9_+-]*)[ \t]*\n?(.*?)```", re.DOTALL)
+
+M = TypeVar("M", bound=BaseModel)
+
+_MISSING = object()
+
+
+def extract_json(text: str | None) -> Any:
+    """Best-effort JSON extraction. Returns ``None`` when nothing parses.
+
+    Tries, in order: the whole reply, each fenced code block, the outermost
+    ``{...}`` span, then the outermost ``[...]`` span.
+    """
+    value = _extract(text)
+    return None if value is _MISSING else value
+
+
+def _extract(text: str | None) -> Any:
+    if not text or not text.strip():
+        return _MISSING
+    candidates = [text.strip()]
+    candidates += [m.group(2).strip() for m in _FENCE.finditer(text)]
+    for open_ch, close_ch in (("{", "}"), ("[", "]")):
+        start, end = text.find(open_ch), text.rfind(close_ch)
+        if start != -1 and end > start:
+            candidates.append(text[start : end + 1])
+    for candidate in candidates:
+        if not candidate:
+            continue
+        try:
+            return json.loads(candidate)
+        except (json.JSONDecodeError, ValueError):
+            continue
+    return _MISSING
+
+
+def _excerpt(text: str, limit: int = 120) -> str:
+    flat = " ".join(text.split())
+    return flat if len(flat) <= limit else flat[: limit - 1] + "…"
+
+
+def parse_json(
+    text: str | None,
+    *,
+    agent: str,
+    expect: type | tuple[type, ...] = dict,
+    schema: type[M] | None = None,
+) -> Any:
+    """Parse an agent's reply as JSON or raise an error naming the agent.
+
+    ``expect`` is the required top-level type (``dict`` by default). With
+    ``schema`` (a pydantic model) the object is validated and the model
+    instance is returned.
+    """
+    if not text or not text.strip():
+        raise EmptyOutputError(agent)
+    value = _extract(text)
+    if value is _MISSING:
+        raise OutputParseError(agent, "no JSON found", _excerpt(text))
+    if not isinstance(value, expect):
+        want = (
+            " or ".join(t.__name__ for t in expect)
+            if isinstance(expect, tuple)
+            else expect.__name__
+        )
+        raise OutputParseError(
+            agent, f"expected a JSON {want}, got {type(value).__name__}", _excerpt(text)
+        )
+    if schema is not None:
+        try:
+            return schema.model_validate(value)
+        except ValidationError as exc:
+            first = exc.errors()[0]
+            loc = ".".join(str(p) for p in first.get("loc", ())) or "(root)"
+            raise OutputParseError(
+                agent, f"JSON does not match {schema.__name__}: {loc}: {first.get('msg')}"
+            ) from exc
+    return value
+
+
+def extract_code_block(text: str | None, language: str = "") -> str | None:
+    """Return the first fenced code block (preferring ``language``), else ``None``."""
+    if not text:
+        return None
+    blocks = [(m.group(1).lower(), m.group(2)) for m in _FENCE.finditer(text)]
+    if not blocks:
+        return None
+    if language:
+        for lang, body in blocks:
+            if lang == language.lower():
+                return body.strip("\n")
+    return blocks[0][1].strip("\n")

crewforge/core/providers.py

@@ -0,0 +1,131 @@
+"""Provider presets for OpenAI-compatible ``/chat/completions`` endpoints.
+
+A preset only supplies *defaults*: base URL, auth header style, a default
+model and the environment variables that hold the key and an optional base-URL
+override. Anything can be overridden explicitly or through the generic
+``CREWFORGE_*`` variables, so any compatible server works via ``custom``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+#: Generic environment variables that apply to whichever provider is active.
+ENV_PROVIDER = "CREWFORGE_PROVIDER"
+ENV_API_KEY = "CREWFORGE_API_KEY"
+ENV_BASE_URL = "CREWFORGE_BASE_URL"
+ENV_MODEL = "CREWFORGE_MODEL"
+
+DEFAULT_PROVIDER = "openai"
+
+
+@dataclass(frozen=True)
+class Provider:
+    name: str
+    label: str
+    base_url: str
+    default_model: str
+    env_key: str
+    env_base: str
+    auth_style: str = "bearer"  # "bearer" -> Authorization: Bearer; "api-key" -> api-key header
+    keyless: bool = False  # local servers that accept requests without a key
+
+
+PROVIDERS: dict[str, Provider] = {
+    p.name: p
+    for p in (
+        Provider(
+            "openai",
+            "OpenAI",
+            "https://api.openai.com/v1",
+            "gpt-4o-mini",
+            "OPENAI_API_KEY",
+            "OPENAI_BASE_URL",
+        ),
+        Provider(
+            "openrouter",
+            "OpenRouter",
+            "https://openrouter.ai/api/v1",
+            "openai/gpt-4o-mini",
+            "OPENROUTER_API_KEY",
+            "OPENROUTER_BASE_URL",
+        ),
+        Provider(
+            "groq",
+            "Groq",
+            "https://api.groq.com/openai/v1",
+            "llama-3.3-70b-versatile",
+            "GROQ_API_KEY",
+            "GROQ_BASE_URL",
+        ),
+        Provider(
+            "deepseek",
+            "DeepSeek",
+            "https://api.deepseek.com/v1",
+            "deepseek-chat",
+            "DEEPSEEK_API_KEY",
+            "DEEPSEEK_BASE_URL",
+        ),
+        Provider(
+            "together",
+            "Together AI",
+            "https://api.together.xyz/v1",
+            "meta-llama/Llama-3.3-70B-Instruct-Turbo",
+            "TOGETHER_API_KEY",
+            "TOGETHER_BASE_URL",
+        ),
+        Provider(
+            "mistral",
+            "Mistral",
+            "https://api.mistral.ai/v1",
+            "mistral-small-latest",
+            "MISTRAL_API_KEY",
+            "MISTRAL_BASE_URL",
+        ),
+        Provider(
+            "ollama",
+            "Ollama (local)",
+            "http://localhost:11434/v1",
+            "llama3.1",
+            "OLLAMA_API_KEY",
+            "OLLAMA_BASE_URL",
+            keyless=True,
+        ),
+        Provider(
+            "llamacpp",
+            "llama.cpp server (local)",
+            "http://localhost:8080/v1",
+            "local",
+            "LLAMACPP_API_KEY",
+            "LLAMACPP_BASE_URL",
+            keyless=True,
+        ),
+        Provider(
+            "mimo",
+            "Xiaomi MiMo",
+            "https://token-plan-sgp.xiaomimimo.com/v1",
+            "mimo-v2.5-pro",
+            "MIMO_API_KEY",
+            "MIMO_BASE_URL",
+            auth_style="api-key",
+        ),
+        Provider(
+            "custom",
+            "Any OpenAI-compatible endpoint",
+            "",  # must be supplied: CREWFORGE_BASE_URL or --base-url
+            "",  # must be supplied: CREWFORGE_MODEL or --model
+            ENV_API_KEY,
+            ENV_BASE_URL,
+            keyless=True,  # many self-hosted servers need no key
+        ),
+    )
+}
+
+
+def get_provider(name: str) -> Provider | None:
+    """Return the preset called ``name`` (case-insensitive), or ``None``."""
+    return PROVIDERS.get((name or "").strip().lower())
+
+
+def provider_names() -> list[str]:
+    return list(PROVIDERS)