agentforge-py 0.2.1__py3-none-any.whl

agentforge/auth.py

@@ -0,0 +1,42 @@
+"""Concrete `AuthPolicy` implementations shipped with the framework
+(feat-014).
+
+`EnvBearerAuth(token_env_var)` reads a comma-separated list of
+valid bearer tokens from an environment variable; each token
+maps to a `Principal` whose id is the token itself. Suitable for
+small/internal deployments; production deployments typically
+implement their own `AuthPolicy` against a real identity
+provider.
+"""
+
+from __future__ import annotations
+
+import os
+
+from agentforge_core.contracts.auth import AuthPolicy
+from agentforge_core.values.auth import Principal
+
+
+class EnvBearerAuth(AuthPolicy):
+    """Bearer-token policy backed by a comma-separated env var.
+
+    Format of ``$<token_env_var>``: ``"token1,token2,token3"``.
+    Each token is its own principal id (no token → identity map).
+    """
+
+    def __init__(self, token_env_var: str = "API_TOKENS") -> None:  # noqa: S107  # nosec B107 — env-var NAME
+        self._var = token_env_var
+
+    async def authenticate(self, bearer_token: str | None) -> Principal | None:
+        if bearer_token is None or not bearer_token:
+            return None
+        raw = os.environ.get(self._var, "")
+        if not raw:
+            return None
+        valid = {t.strip() for t in raw.split(",") if t.strip()}
+        if bearer_token in valid:
+            return Principal(id=bearer_token)
+        return None
+
+
+__all__ = ["EnvBearerAuth"]

agentforge/cli/__init__.py

@@ -0,0 +1,18 @@
+"""`agentforge` CLI (feat-010).
+
+Read-only commands only in this PR:
+- `agentforge list modules [--category <cat>]`
+
+The destructive commands (`add`, `swap`, `remove`) edit
+`agentforge.yaml` and apply a per-module `manifest.yaml`. Both
+depend on feat-012 (Configuration system); they ship as a follow-
+up sub-feat once that lands.
+
+Entry point: `[project.scripts] agentforge = "agentforge.cli.main:main"`.
+"""
+
+from __future__ import annotations
+
+from agentforge.cli.main import main
+
+__all__ = ["main"]

agentforge/cli/_build.py

@@ -0,0 +1,323 @@
+"""Shared CLI helper: build an `Agent` from `agentforge.yaml` (feat-017).
+
+`agentforge run`, `eval`, `debug`, `db ...`, and `health` all need to
+go from a config file on disk to a ready-to-run `Agent`. This module
+centralises that wiring so each command stays small.
+
+The helper:
+
+1. Loads + validates the config (feat-012's `load_config`).
+2. Resolves every module declared in `modules.*` and `agent.*` via
+   the global `Resolver` (feat-010).
+3. Instantiates each module with the per-entry `config` dict.
+4. Hands the wired-up objects to `Agent(...)`.
+5. Optionally installs the recording hook from feat-017 chunk 1
+   when `enable_recording=True` is set.
+
+Errors are surfaced as `ModuleError` so the CLI can map them to
+deterministic exit codes (per feat-017 §4 — config invalid → 2).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from agentforge_core.config.loader import load_config
+from agentforge_core.config.schema import AgentForgeConfig
+from agentforge_core.contracts.embedding import EmbeddingClient
+from agentforge_core.contracts.evaluator import Evaluator
+from agentforge_core.contracts.graph_store import GraphStore
+from agentforge_core.contracts.llm import LLMClient
+from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.contracts.reranker import Reranker
+from agentforge_core.contracts.vector_store import VectorStore
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.resolver import Resolver
+from agentforge_core.values.retrieval import GraphExpansion
+
+from agentforge.agent import Agent
+from agentforge.memory import InMemoryStore
+from agentforge.pipeline import Pipeline
+from agentforge.retrieval import Retriever
+
+if TYPE_CHECKING:
+    from agentforge_core.contracts.tool import Tool
+
+
+async def load_and_build(
+    *,
+    path: Path | str | None = None,
+    env: str | None = None,
+    overrides: list[str] | None = None,
+    enable_recording: bool = False,
+) -> Agent:
+    """Load config (feat-012) and construct a wired `Agent`.
+
+    Sole entrypoint every CLI command uses. Honours
+    `AGENTFORGE_CONFIG` / `AGENTFORGE_ENV` env vars (resolved inside
+    `load_config`); accepts dotted-path overrides like
+    `agent.budget.usd=5.0`.
+    """
+    config = load_config(path, env=env, overrides=overrides)
+    return await build_agent_from_config(config, enable_recording=enable_recording)
+
+
+async def build_agent_from_config(
+    config: AgentForgeConfig,
+    *,
+    enable_recording: bool = False,
+) -> Agent:
+    """Build an `Agent` from an already-loaded `AgentForgeConfig`.
+
+    Splits out from `load_and_build` for tests + reuse — tests build
+    a `AgentForgeConfig` directly and skip the YAML parse.
+    """
+    memory = build_memory_from_config(config)
+    if memory is not None:
+        await _maybe_init_schema(memory)
+    evaluators = build_evaluators_from_config(config)
+    pipeline = build_pipeline_from_config(config)
+    retriever = build_retriever_from_config(config)
+    llm = _resolve_llm(config)
+    strategy = config.agent.strategy if isinstance(config.agent.strategy, str) else None
+
+    return Agent(
+        model=llm,
+        memory=memory if memory is not None else InMemoryStore(),
+        evaluators=evaluators,
+        strategy=strategy,
+        retriever=retriever,
+        system_prompt=config.agent.system_prompt,
+        budget_usd=config.agent.budget.usd,
+        max_iterations=config.agent.max_iterations,
+        record_runs=memory if enable_recording and memory is not None else None,
+        pipeline=pipeline,
+    )
+
+
+def build_memory_from_config(config: AgentForgeConfig) -> MemoryStore | None:
+    """Resolve + instantiate `modules.memory`. Returns None when absent."""
+    if config.modules.memory is None:
+        return None
+    cls = _resolve_class("memory", config.modules.memory.driver)
+    instance = _instantiate(cls, config.modules.memory.config)
+    if not isinstance(instance, MemoryStore):
+        msg = (
+            f"Resolved memory driver {config.modules.memory.driver!r} "
+            f"({cls.__name__}) does not implement MemoryStore."
+        )
+        raise ModuleError(msg)
+    return instance
+
+
+def build_evaluators_from_config(config: AgentForgeConfig) -> list[Evaluator]:
+    """Resolve + instantiate every entry in `modules.evaluators`."""
+    out: list[Evaluator] = []
+    for entry in config.modules.evaluators:
+        cls = _resolve_class("evaluators", entry.name)
+        instance = _instantiate(cls, entry.config)
+        if not isinstance(instance, Evaluator):
+            msg = (
+                f"Resolved evaluator {entry.name!r} ({cls.__name__}) does not implement Evaluator."
+            )
+            raise ModuleError(msg)
+        out.append(instance)
+    return out
+
+
+def build_pipeline_from_config(config: AgentForgeConfig) -> Pipeline | None:
+    """Resolve + instantiate `modules.pipeline.tasks` (feat-015).
+
+    Returns ``None`` when the pipeline block is absent, disabled, or
+    has no tasks. Each task name resolves under the `"tasks"`
+    resolver category (register via
+    `agentforge.resolver_register.register_task` or via an
+    `agentforge.tasks` entry point).
+    """
+    from agentforge_core.contracts.task import Task as TaskBase  # noqa: PLC0415
+
+    cfg = config.modules.pipeline
+    if cfg is None or not cfg.enabled or not cfg.tasks:
+        return None
+    tasks: list[TaskBase] = []
+    for entry in cfg.tasks:
+        cls = _resolve_class("tasks", entry.name)
+        instance = _instantiate(cls, entry.config)
+        if not isinstance(instance, TaskBase):
+            msg = f"Resolved task {entry.name!r} ({cls.__name__}) does not implement Task."
+            raise ModuleError(msg)
+        tasks.append(instance)
+    return Pipeline(
+        tasks,
+        max_concurrent=cfg.max_concurrent,
+        on_task_error=cfg.on_task_error,
+    )
+
+
+def build_retriever_from_config(config: AgentForgeConfig) -> Retriever | None:
+    """Resolve + instantiate the top-level `retrieval:` block.
+
+    feat-021 follow-up. Returns ``None`` when no `retrieval:`
+    block is set. Otherwise resolves three sub-components:
+
+    - ``retrieval.vector_store.driver`` → ``vector_stores``
+      category → instantiated `VectorStore`.
+    - ``retrieval.embedder.driver`` → ``embeddings`` category →
+      instantiated `EmbeddingClient`.
+    - ``retrieval.reranker.name`` (optional) → ``rerankers``
+      category → instantiated `Reranker`.
+
+    The three are wired into a `Retriever` with the top-level
+    knobs (``top_k`` / ``over_fetch_factor`` / ``batch_size``)
+    forwarded to its constructor.
+
+    Raises:
+        ModuleError: a referenced module isn't registered or
+            its instance doesn't implement the expected ABC.
+    """
+    r = config.retrieval
+    if r is None:
+        return None
+
+    store_cls = _resolve_class("vector_stores", r.vector_store.driver)
+    store = _instantiate(store_cls, r.vector_store.config)
+    if not isinstance(store, VectorStore):
+        msg = (
+            f"Resolved vector_store {r.vector_store.driver!r} "
+            f"({store_cls.__name__}) does not implement VectorStore."
+        )
+        raise ModuleError(msg)
+
+    embedder_cls = _resolve_class("embeddings", r.embedder.driver)
+    embedder = _instantiate(embedder_cls, r.embedder.config)
+    if not isinstance(embedder, EmbeddingClient):
+        msg = (
+            f"Resolved embedder {r.embedder.driver!r} "
+            f"({embedder_cls.__name__}) does not implement EmbeddingClient."
+        )
+        raise ModuleError(msg)
+
+    reranker: Reranker | None = None
+    if r.reranker is not None:
+        reranker_cls = _resolve_class("rerankers", r.reranker.name)
+        reranker_instance = _instantiate(reranker_cls, r.reranker.config)
+        if not isinstance(reranker_instance, Reranker):
+            msg = (
+                f"Resolved reranker {r.reranker.name!r} "
+                f"({reranker_cls.__name__}) does not implement Reranker."
+            )
+            raise ModuleError(msg)
+        reranker = reranker_instance
+
+    graph_expansion: GraphExpansion | None = None
+    if r.graph_expansion is not None:
+        ge_cfg = r.graph_expansion
+        graph_store_cls = _resolve_class("graph_stores", ge_cfg.store.driver)
+        graph_store_instance = _instantiate(graph_store_cls, ge_cfg.store.config)
+        if not isinstance(graph_store_instance, GraphStore):
+            msg = (
+                f"Resolved graph_store {ge_cfg.store.driver!r} "
+                f"({graph_store_cls.__name__}) does not implement GraphStore."
+            )
+            raise ModuleError(msg)
+        graph_expansion = GraphExpansion(
+            store=graph_store_instance,
+            max_hops=ge_cfg.max_hops,
+            edge_types=tuple(ge_cfg.edge_types) if ge_cfg.edge_types is not None else None,
+            text_property=ge_cfg.text_property,
+            decay=ge_cfg.decay,
+        )
+
+    return Retriever(
+        store=store,
+        embedder=embedder,
+        reranker=reranker,
+        top_k=r.top_k,
+        over_fetch_factor=r.over_fetch_factor,
+        batch_size=r.batch_size,
+        mode=r.mode,
+        rrf_k=r.rrf_k,
+        graph_expansion=graph_expansion,
+    )
+
+
+def build_tools_from_config(config: AgentForgeConfig) -> list[Tool]:
+    """Resolve tools listed under `agent.tools` (string or dict form)."""
+    from agentforge_core.contracts.tool import Tool as ToolBase  # noqa: PLC0415
+
+    tools: list[ToolBase] = []
+    for entry in config.agent.tools:
+        name = entry if isinstance(entry, str) else next(iter(entry))
+        cfg = {} if isinstance(entry, str) else entry[name]
+        cls = _resolve_class("tools", name)
+        instance = _instantiate(cls, cfg)
+        if not isinstance(instance, ToolBase):
+            msg = f"Resolved tool {name!r} ({cls.__name__}) does not implement Tool."
+            raise ModuleError(msg)
+        tools.append(instance)
+    return tools
+
+
+def _resolve_llm(config: AgentForgeConfig) -> LLMClient | str | None:
+    """Pick the LLM definition out of `config.agent.model` /
+    `config.providers["default"]`.
+
+    We hand a string back to `Agent.__init__` when the model is a
+    plain `"<provider>:<model>"` string — `Agent` already knows how
+    to resolve that. When `agent.model` is missing but
+    `providers["default"]` is present, we synthesize the string from
+    the named-provider record.
+    """
+    raw = config.agent.model
+    if isinstance(raw, str):
+        return raw
+    default = config.providers.get("default")
+    if default is None or default.model is None:
+        return None
+    return f"{default.type}:{default.model}"
+
+
+def _resolve_class(category: str, name: str) -> type:
+    return Resolver.global_().resolve(category, name)
+
+
+def _instantiate(cls: type, cfg: dict[str, Any]) -> Any:
+    """Construct an instance of `cls` from a YAML config dict.
+
+    Preference order:
+
+    1. ``cls.from_config(**cfg)`` — keyword-friendly factory
+       (preferred for new modules; matches the
+       `SentenceTransformersReranker.from_config(*, model=...)`
+       shape from feat-021).
+    2. ``cls.from_config(cfg)`` — legacy dict-positional shape
+       (no in-tree callers today; kept as a defensive fallback
+       so externally-shipped modules that ship the older shape
+       still load).
+    3. ``cls(**cfg)`` — plain constructor.
+    """
+    from_config = getattr(cls, "from_config", None)
+    if callable(from_config):
+        try:
+            return from_config(**cfg)
+        except TypeError:
+            return from_config(cfg)
+    return cls(**cfg)
+
+
+async def _maybe_init_schema(memory: MemoryStore) -> None:
+    init = getattr(memory, "init_schema", None)
+    if callable(init):
+        await init()
+
+
+__all__ = [
+    "build_agent_from_config",
+    "build_evaluators_from_config",
+    "build_memory_from_config",
+    "build_pipeline_from_config",
+    "build_retriever_from_config",
+    "build_tools_from_config",
+    "load_and_build",
+]

agentforge/cli/_scaffold_state.py

@@ -0,0 +1,250 @@
+"""Lock-file + marker-header machinery for feat-011 chunks 3-5.
+
+State layout (per spec §4.2):
+
+    .agentforge-state/
+    ├── answers.yml          # Copier answers, written by Copier itself
+    └── managed-files.lock   # { path: { hash, source_module,
+                                         source_version,
+                                         forked: bool } }
+
+Marker header form (per spec §4.2):
+
+    AGENTFORGE-MANAGED: <module>@<version> hash:<sha256-prefix>
+
+Where `<module>` is `template:<template-name>` for files from
+`agentforge new`, or `<distribution>` for files from
+`agentforge add module`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+import yaml
+from agentforge_core.production.exceptions import ModuleError
+
+_STATE_DIR = Path(".agentforge-state")
+_LOCK_FILE = _STATE_DIR / "managed-files.lock"
+_ANSWERS_FILE = _STATE_DIR / "answers.yml"
+
+_MARKER_PREFIX = "AGENTFORGE-MANAGED:"
+_HASH_PREFIX_LEN = 12
+
+
+def lock_path(cwd: Path) -> Path:
+    return cwd / _LOCK_FILE
+
+
+def answers_path(cwd: Path) -> Path:
+    return cwd / _ANSWERS_FILE
+
+
+def read_lock(cwd: Path) -> dict[str, dict[str, Any]]:
+    """Read the managed-files lock. Empty dict if absent."""
+    path = lock_path(cwd)
+    if not path.exists():
+        return {}
+    with path.open() as fh:
+        raw = yaml.safe_load(fh) or {}
+    if not isinstance(raw, dict):
+        raise ModuleError(f"{path} must be a top-level mapping; got {type(raw).__name__}.")
+    return raw
+
+
+def write_lock(cwd: Path, lock: dict[str, dict[str, Any]]) -> None:
+    """Write the managed-files lock; creates the state dir."""
+    path = lock_path(cwd)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as fh:
+        yaml.safe_dump(lock, fh, sort_keys=True)
+
+
+def hash_content(content: str) -> str:
+    """sha256 of `content` UTF-8 encoded. Caller takes a prefix."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def marker_for(
+    suffix: str, source_module: str, source_version: str, hash_prefix: str
+) -> str | None:
+    """Format the marker header line for a file with the given suffix.
+
+    Returns `None` for file extensions where comment markers aren't
+    practical (e.g. binary). Suffixes follow the same per-language
+    mapping as feat-010b's manifest applier.
+    """
+    body = f"{_MARKER_PREFIX} {source_module}@{source_version} hash:{hash_prefix}"
+    if suffix in {".py", ".sh", ".yaml", ".yml", ".toml", ".ini", ".env", ".sql", ".cfg"}:
+        return f"# {body}"
+    if suffix in {".js", ".ts", ".tsx", ".jsx", ".css"}:
+        return f"// {body}"
+    if suffix in {".html", ".xml", ".md"}:
+        return f"<!-- {body} -->"
+    return None
+
+
+def write_managed_files_lock(
+    cwd: Path,
+    *,
+    template_name: str,
+    template_version: str,
+    rendered_root: Path | None = None,
+) -> dict[str, dict[str, Any]]:
+    """Walk `cwd`, write a lock entry for every framework-managed
+    file, return the lock dict.
+
+    `rendered_root` defaults to `cwd`; pass a different path when
+    running against a Copier-rendered scaffold that isn't the cwd.
+
+    Files counted as "managed" are every file the template produced.
+    Identification is by the framework marker header: any file with
+    the `AGENTFORGE-MANAGED:` line at the top counts. For the
+    initial scaffold (no markers yet), the caller writes the lock
+    from the Copier render's file list — see `prepend_markers`.
+    """
+    root = rendered_root if rendered_root is not None else cwd
+    lock: dict[str, dict[str, Any]] = {}
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(root)
+        # Skip the state dir itself.
+        if rel.parts and rel.parts[0] == _STATE_DIR.name:
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue  # binary or unreadable — skip
+        h = hash_content(content)
+        lock[str(rel).replace("\\", "/")] = {
+            "hash": h,
+            "source_module": f"template:{template_name}",
+            "source_version": template_version,
+            "forked": False,
+        }
+    write_lock(cwd, lock)
+    return lock
+
+
+def prepend_markers(
+    cwd: Path,
+    *,
+    template_name: str,
+    template_version: str,
+) -> None:
+    """For every file in the lock that supports a comment-marker
+    extension, prepend `# AGENTFORGE-MANAGED: ...` if not already
+    present. Idempotent."""
+    lock = read_lock(cwd)
+    for rel_path, entry in lock.items():
+        path = cwd / rel_path
+        if not path.exists():
+            continue
+        suffix = path.suffix
+        marker = marker_for(
+            suffix,
+            entry.get("source_module", f"template:{template_name}"),
+            entry.get("source_version", template_version),
+            entry["hash"][:_HASH_PREFIX_LEN],
+        )
+        if marker is None:
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        if _MARKER_PREFIX in content.split("\n", 1)[0]:
+            continue  # already marked
+        path.write_text(marker + "\n" + content, encoding="utf-8")
+
+
+def strip_marker(path: Path) -> bool:
+    """Strip the framework marker header (if present) from `path`.
+
+    Returns True if a marker was stripped. Used by `agentforge fork`.
+    """
+    if not path.exists():
+        return False
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return False
+    lines = content.split("\n", 1)
+    if not lines or _MARKER_PREFIX not in lines[0]:
+        return False
+    rest = lines[1] if len(lines) > 1 else ""
+    path.write_text(rest, encoding="utf-8")
+    return True
+
+
+def file_status(cwd: Path, rel_path: str, entry: dict[str, Any]) -> str:
+    """Classify a tracked file as 'managed', 'forked', 'drifted', or
+    'missing'."""
+    if entry.get("forked"):
+        return "forked"
+    path = cwd / rel_path
+    if not path.exists():
+        return "missing"
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return "managed"
+    # Strip the framework marker line before hashing — markers
+    # change the bytes-on-disk but not the underlying content.
+    body = _strip_marker_for_hash(content)
+    if hash_content(body) == entry["hash"]:
+        return "managed"
+    return "drifted"
+
+
+def _strip_marker_for_hash(content: str) -> str:
+    """Drop the leading AGENTFORGE-MANAGED line for hash comparison."""
+    if _MARKER_PREFIX not in content.split("\n", 1)[0]:
+        return content
+    parts = content.split("\n", 1)
+    return parts[1] if len(parts) > 1 else ""
+
+
+# ----------------------------------------------------------------------
+# Three-section managed / custom format (feat-019)
+# ----------------------------------------------------------------------
+
+END_MANAGED_MARKER = "<!-- agentforge:end-managed -->"
+"""Closes the framework-managed section. Anything after this marker is
+developer-owned (the custom section) and survives upgrades."""
+
+CUSTOM_START_MARKER = "<!-- agentforge:custom -->"
+CUSTOM_END_MARKER = "<!-- agentforge:end-custom -->"
+
+
+def split_three_section(content: str) -> tuple[str, str]:
+    """Split markdown / text content into (managed, custom).
+
+    The managed section is everything up to and including the
+    `<!-- agentforge:end-managed -->` marker. The custom section is
+    everything after that. Returns (managed, custom). When the marker
+    is absent, the entire content is treated as managed.
+    """
+    if END_MANAGED_MARKER not in content:
+        return content, ""
+    head, _, tail = content.partition(END_MANAGED_MARKER)
+    managed = head + END_MANAGED_MARKER
+    custom = tail
+    return managed, custom
+
+
+def merge_three_section(new_managed: str, existing_custom: str) -> str:
+    """Stitch a freshly rendered managed section onto a preserved
+    custom section.
+
+    `new_managed` should already include the `END_MANAGED_MARKER`. If
+    it doesn't, the marker is appended so the on-disk file remains
+    parseable by future `split_three_section` calls.
+    """
+    managed = new_managed
+    if END_MANAGED_MARKER not in managed:
+        managed = managed.rstrip() + "\n\n" + END_MANAGED_MARKER + "\n"
+    return managed.rstrip() + "\n" + existing_custom.lstrip("\n")