agentforge-core 0.2.1__py3-none-any.whl

agentforge_core/values/__init__.py

@@ -0,0 +1,103 @@
+"""Locked value types — Pydantic v2 models the framework's contracts use.
+
+Per ADR-0007, these shapes are part of the framework's stable surface;
+adding a field requires a minor bump, removing or renaming a field
+requires a major bump.
+"""
+
+from __future__ import annotations
+
+from agentforge_core.values.auth import Principal
+from agentforge_core.values.chat import (
+    ChatChunk,
+    ChatChunkKind,
+    ChatResponse,
+    ChatRole,
+    ChatTurn,
+    SessionInfo,
+    StreamingChunkKind,
+    StreamingEvent,
+)
+from agentforge_core.values.claim import Claim
+from agentforge_core.values.graph import (
+    GraphEdge,
+    GraphNode,
+    GraphPattern,
+    GraphSegment,
+    Path,
+)
+from agentforge_core.values.manifest import (
+    AppliedEnvVar,
+    AppliedManifest,
+    AppliedTemplate,
+    EnvVarEntry,
+    Manifest,
+    TemplateFile,
+)
+from agentforge_core.values.messages import (
+    EmbeddingResponse,
+    LLMResponse,
+    Message,
+    MessageRole,
+    StopReason,
+    StreamChunk,
+    StreamChunkKind,
+    TokenUsage,
+    ToolCall,
+    ToolSpec,
+)
+from agentforge_core.values.module import ModuleInfo
+from agentforge_core.values.pipeline import PipelineResult
+from agentforge_core.values.retrieval import GraphExpansion
+from agentforge_core.values.state import (
+    AgentState,
+    FinishReason,
+    RunResult,
+    Step,
+    StepKind,
+)
+from agentforge_core.values.vector import VectorItem, VectorMatch
+
+__all__ = [
+    "AgentState",
+    "AppliedEnvVar",
+    "AppliedManifest",
+    "AppliedTemplate",
+    "ChatChunk",
+    "ChatChunkKind",
+    "ChatResponse",
+    "ChatRole",
+    "ChatTurn",
+    "Claim",
+    "EmbeddingResponse",
+    "EnvVarEntry",
+    "FinishReason",
+    "GraphEdge",
+    "GraphExpansion",
+    "GraphNode",
+    "GraphPattern",
+    "GraphSegment",
+    "LLMResponse",
+    "Manifest",
+    "Message",
+    "MessageRole",
+    "ModuleInfo",
+    "Path",
+    "PipelineResult",
+    "Principal",
+    "RunResult",
+    "SessionInfo",
+    "Step",
+    "StepKind",
+    "StopReason",
+    "StreamChunk",
+    "StreamChunkKind",
+    "StreamingChunkKind",
+    "StreamingEvent",
+    "TemplateFile",
+    "TokenUsage",
+    "ToolCall",
+    "ToolSpec",
+    "VectorItem",
+    "VectorMatch",
+]

agentforge_core/values/auth.py

@@ -0,0 +1,20 @@
+"""Auth value types (feat-014).
+
+`Principal` is the identity returned by an `AuthPolicy` after a
+successful authentication. Carries an opaque ``id`` (the token
+itself by default; an opaque user id once a real identity
+provider is wired) plus optional metadata for downstream use
+(role tags, tenant id, etc.).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Identity returned by `AuthPolicy.authenticate(...)`."""
+
+    id: str
+    metadata: dict[str, str] = field(default_factory=dict)

agentforge_core/values/chat.py

@@ -0,0 +1,131 @@
+"""Chat-agent value types (feat-020).
+
+Frozen Pydantic models that ride the wire between `ChatSession`,
+`ChatHistoryStore` drivers, and the chat-http server.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agentforge_core.values.messages import ToolCall
+
+ChatRole = Literal["user", "assistant", "system", "tool"]
+"""Closed enum of chat turn roles."""
+
+StreamingChunkKind = Literal[
+    "text",
+    "thinking",
+    "step",
+    "tool_call",
+    "tool_result",
+    "done",
+    "error",
+]
+"""Closed enum of streaming chunk kinds shared across chat (token-level)
+and A2A (step + token-level) wire formats. Adding a new kind requires a
+minor version bump per ADR-0007. Receivers must ignore unknown kinds on
+the wire — forward-compat for future additions.
+
+The ``step`` kind is reserved for strategies that emit step-level
+events alongside (or instead of) per-token text. Chat receivers
+typically ignore it; A2A clients render it as a generic step boundary.
+"""
+
+ChatChunkKind = StreamingChunkKind
+"""Backward-compatible alias retained for callers that imported the
+chat-shaped name in feat-020 v0.1 / v0.2. Prefer ``StreamingChunkKind``
+in new code."""
+
+
+class ChatTurn(BaseModel):
+    """One persisted message in a chat session.
+
+    Stored by `ChatHistoryStore` drivers, surfaced through
+    `ChatSession.history()`, and emitted on the chat-http wire.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    id: str
+    session_id: str
+    role: ChatRole
+    content: str
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    run_id: str | None = None
+    """Links assistant turns (and the tool turns produced inside them)
+    back to the AgentForge run that emitted them. None for user /
+    system turns."""
+    tool_calls: tuple[ToolCall, ...] = ()
+    tool_call_id: str | None = None
+    tokens_in: int = Field(default=0, ge=0)
+    tokens_out: int = Field(default=0, ge=0)
+    cost_usd: float = Field(default=0.0, ge=0.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class SessionInfo(BaseModel):
+    """Session-level metadata returned by `list_sessions` /
+    `delete_session` / `update_session_metadata`."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    id: str
+    owner: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    last_active_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    turn_count: int = Field(default=0, ge=0)
+    total_cost_usd: float = Field(default=0.0, ge=0.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ChatChunk(BaseModel):
+    """One streaming chunk emitted by `ChatSession.stream()` /
+    `ChatServer` SSE+WS."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    kind: ChatChunkKind
+    content: str | dict[str, Any] | None = None
+    cumulative_text: str | None = None
+    turn_id: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ChatResponse(BaseModel):
+    """Aggregated response returned by `ChatSession.send()`."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    content: str
+    turn_id: str
+    run_id: str
+    tool_calls: tuple[ToolCall, ...] = ()
+    tokens_in: int = Field(default=0, ge=0)
+    tokens_out: int = Field(default=0, ge=0)
+    cost_usd: float = Field(default=0.0, ge=0.0)
+    duration_ms: int = Field(default=0, ge=0)
+    finish_reason: str = "completed"
+
+
+class StreamingEvent(BaseModel):
+    """One event emitted by `ReasoningStrategy.stream()` (feat-020 v0.2).
+
+    Strategies that want per-token streaming override the default
+    `stream()` to yield these events as the LLM emits tokens / step
+    transitions. `ChatSession.stream()` forwards each event to a
+    `ChatChunk` on the wire (kinds map 1:1 with `ChatChunkKind`).
+    The default base-class `stream()` calls `run()` and yields a
+    single `done` event so existing concrete strategies keep
+    working unchanged.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    kind: ChatChunkKind
+    content: str | dict[str, Any] | None = None
+    cumulative_text: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)

agentforge_core/values/claim.py

@@ -0,0 +1,30 @@
+"""`Claim` — a persisted unit of agent-produced knowledge.
+
+Written through `MemoryStore`. The `(project, agent)` pair namespaces
+claims; cross-agent and cross-project queries are explicit verbs (per
+feat-005 design). `id` is a ULID for sortable monotonic ordering.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from ulid import ULID
+
+
+class Claim(BaseModel):
+    """A persisted unit of agent-produced knowledge."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    id: str = Field(default_factory=lambda: str(ULID()))
+    run_id: str
+    project: str
+    agent: str
+    category: str
+    payload: dict[str, Any]
+    supersedes: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    metadata: dict[str, Any] = Field(default_factory=dict)

agentforge_core/values/graph.py

@@ -0,0 +1,136 @@
+"""Frozen value types for the `GraphStore` contract.
+
+`GraphNode` and `GraphEdge` are what callers upsert; `GraphPattern`
+(composed of `GraphSegment`) is the query DSL `match()` accepts; `Path`
+is what `match()` and `traverse()` return. All immutable Pydantic
+models — safe to pass across async boundaries without aliasing bugs.
+
+Per ADR-0007 these shapes are part of the framework's locked surface.
+Adding a field is a minor bump; removing or renaming requires a major
+bump.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class GraphNode(BaseModel):
+    """One node in a `GraphStore`.
+
+    Attributes:
+        id: Caller-controlled identifier. Re-upserting an existing id
+            replaces the prior record (write-through, not append).
+        labels: Type tags. Empty tuple is allowed — nodes without
+            labels are still queryable by id and properties. Order is
+            insignificant; drivers may sort internally.
+        properties: Free-form key-value attributes. Used by
+            `GraphPattern.node_filters` for AND-style equality
+            filtering during `match()`.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    id: str = Field(min_length=1)
+    labels: tuple[str, ...] = Field(default_factory=tuple)
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphEdge(BaseModel):
+    """One directed edge in a `GraphStore`.
+
+    Attributes:
+        src: Source node id. Drivers must reject edges referring to
+            absent nodes (raise `ValueError`); `add_node` first.
+        dst: Destination node id. Same constraint as `src`.
+        edge_type: Relationship type, e.g. `"CITES"`, `"AUTHORED_BY"`.
+            Required and non-empty (the field name `type` would shadow
+            the builtin, hence `edge_type`).
+        properties: Free-form key-value attributes on the edge itself
+            (weight, timestamp, etc.).
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    src: str = Field(min_length=1)
+    dst: str = Field(min_length=1)
+    edge_type: str = Field(min_length=1)
+    properties: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphSegment(BaseModel):
+    """One hop in a `GraphPattern`.
+
+    `None` for `src_label`, `edge_type`, or `dst_label` is a wildcard
+    at that position. `direction` controls how the edge is matched
+    against the underlying store — `"out"` is the default and matches
+    `src -> dst`; `"in"` matches `dst <- src` (i.e. reversed); `"any"`
+    matches either direction.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    src_label: str | None = None
+    edge_type: str | None = None
+    dst_label: str | None = None
+    direction: Literal["out", "in", "any"] = "out"
+
+
+class GraphPattern(BaseModel):
+    """A chained pattern for `GraphStore.match`.
+
+    `segments` is the ordered chain of hops (length 1 = one edge).
+    `node_filters` is an optional sequence of equality filters indexed
+    by node-position: position 0 is the start node, position 1 is the
+    destination of segment 0, position 2 is the destination of segment
+    1, and so on. Length must be either 0 (no filters), or `len(segments) + 1`.
+
+    Example: matching `(:Doc {topic="ml"})-[:CITES]->(:Doc)` becomes
+    ``GraphPattern(segments=(GraphSegment(src_label="Doc",
+    edge_type="CITES", dst_label="Doc"),),
+    node_filters=({"topic": "ml"}, {}))``.
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    segments: tuple[GraphSegment, ...] = Field(min_length=1)
+    node_filters: tuple[dict[str, Any], ...] = Field(default_factory=tuple)
+
+    @model_validator(mode="after")
+    def _filters_match_segments(self) -> GraphPattern:
+        if self.node_filters and len(self.node_filters) != len(self.segments) + 1:
+            msg = (
+                f"node_filters length {len(self.node_filters)} must equal "
+                f"len(segments) + 1 = {len(self.segments) + 1} (one filter "
+                f"per node position) or be empty"
+            )
+            raise ValueError(msg)
+        return self
+
+
+class Path(BaseModel):
+    """An ordered chain of nodes connected by edges.
+
+    Returned by both `match()` and `traverse()`. Invariants enforced:
+      - at least one node
+      - `len(edges) == len(nodes) - 1`
+      - each edge `i` connects `nodes[i]` to `nodes[i+1]` (drivers
+        respect this; the value type doesn't re-check the topology
+        beyond length, since per-edge id checking would require
+        property-level equality which is wasteful)
+    """
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    nodes: tuple[GraphNode, ...] = Field(min_length=1)
+    edges: tuple[GraphEdge, ...] = Field(default_factory=tuple)
+
+    @model_validator(mode="after")
+    def _edges_count_matches_nodes(self) -> Path:
+        expected = len(self.nodes) - 1
+        if len(self.edges) != expected:
+            msg = f"edges length {len(self.edges)} must equal len(nodes) - 1 = {expected}"
+            raise ValueError(msg)
+        return self

agentforge_core/values/guardrails.py

@@ -0,0 +1,49 @@
+"""Guardrail runtime value types (feat-018).
+
+`ValidationResult` is the locked return shape every `InputValidator`,
+`OutputValidator`, and `ToolCallGate` produces. The framework-wide
+`GuardrailPolicy` lives in `agentforge_core.config.schema` instead
+of here — co-locating it with the other config models avoids the
+import cycle through `values.state`.
+
+Per ADR-0009 this shape is frozen so it crosses process / module
+boundaries safely.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ValidationResult(BaseModel):
+    """Outcome of one validator's `validate(...)` / `authorize(...)` call."""
+
+    model_config = ConfigDict(frozen=True, strict=True)
+
+    passed: bool
+    score: float = Field(default=1.0, ge=0.0, le=1.0)
+    """Confidence; 1.0 = definitely clean, 0.0 = definitely bad. Used
+    by redaction-vs-block policy thresholds and audit aggregation."""
+
+    violations: tuple[str, ...] = ()
+    """Rule identifiers that fired (e.g. `("prompt_injection", "jailbreak")`).
+    Empty tuple when `passed=True`."""
+
+    redacted_content: str | None = None
+    """If the validator can both flag AND redact, the post-redaction
+    string. Output validators with `policy.on_output_violation =
+    "redact"` use this; input validators usually only flag."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Validator-specific extra detail — scores per entity, spans,
+    upstream raw payload. Never required, never relied on."""
+
+    @classmethod
+    def ok(cls) -> ValidationResult:
+        """Clean-pass result with no violations and full confidence."""
+        return cls(passed=True)
+
+
+__all__ = ["ValidationResult"]

agentforge_core/values/manifest.py

@@ -0,0 +1,129 @@
+"""Manifest value types for `agentforge add/swap/remove module` (feat-010b).
+
+Each Tier-3 module ships a `manifest.yaml` at the root of its
+package describing the side-effects `agentforge add module X` should
+apply to a consuming agent's repo:
+
+    # agentforge_memory_postgres/manifest.yaml
+    category: memory
+    name: postgres
+    env_vars:
+      - name: POSTGRES_DSN
+        description: "Connection string"
+        required: true
+    templates:
+      - source: db/migrations/0001_init.sql
+        destination: db/migrations/agentforge/0001_init.sql
+    config_block:
+      modules:
+        memory:
+          driver: postgres
+          config:
+            dsn: "${POSTGRES_DSN}"
+    next_steps:
+      - "Set POSTGRES_DSN in your .env file."
+      - "Run `agentforge db migrate` to apply the schema."
+
+The applier serialises what it actually did into an `AppliedManifest`
+state file at `.agentforge-state/manifests/<distribution>.yaml`, so
+`agentforge remove module X` can reverse the application.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EnvVarEntry(BaseModel):
+    """One env-var the module needs. Appended to `.env.example` on apply."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    name: str = Field(min_length=1)
+    description: str = ""
+    required: bool = True
+    default: str | None = None
+
+
+class TemplateFile(BaseModel):
+    """A file the module ships that gets copied into the agent repo."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    source: str = Field(min_length=1)
+    """Path inside the module package (relative to the package root)."""
+
+    destination: str = Field(min_length=1)
+    """Path in the consuming repo (relative to cwd at `add` time)."""
+
+    overwrite: bool = False
+    """Whether to overwrite an existing destination. Default False —
+    a pre-existing file aborts the apply with a clear error."""
+
+
+class Manifest(BaseModel):
+    """Parsed `manifest.yaml`. Source of truth for what `add` does."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    category: str = Field(min_length=1)
+    """Module category (`memory`, `tools`, `providers`, etc.) —
+    must match the entry-point group suffix."""
+
+    name: str = Field(min_length=1)
+    """Module name within the category (e.g. `postgres`)."""
+
+    env_vars: list[EnvVarEntry] = Field(default_factory=list)
+    templates: list[TemplateFile] = Field(default_factory=list)
+    config_block: dict[str, Any] = Field(default_factory=dict)
+    """A nested-dict snippet to deep-merge into `agentforge.yaml`."""
+
+    next_steps: list[str] = Field(default_factory=list)
+    """Free-form lines printed after a successful `add`."""
+
+
+class AppliedEnvVar(BaseModel):
+    """Record of an env var the applier appended to `.env.example`."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    name: str = Field(min_length=1)
+    line: str = Field(min_length=1)
+    """The exact line written, so `remove` can match-and-strip it."""
+
+
+class AppliedTemplate(BaseModel):
+    """Record of a file the applier created."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    destination: str = Field(min_length=1)
+    """Path relative to cwd; safe to `unlink` on `remove`."""
+
+
+class AppliedManifest(BaseModel):
+    """State file at `.agentforge-state/manifests/<distribution>.yaml`.
+
+    Records exactly what `agentforge add module X` wrote, so
+    `agentforge remove module X` can reverse it. Atomic at the
+    individual-step level (each list reflects what *did* land);
+    apply failures partway through still write the state for what
+    succeeded so `remove` can clean up.
+    """
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    distribution: str = Field(min_length=1)
+    """The `agentforge-X` distribution name."""
+
+    category: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    """Mirrors `Manifest.category` / `Manifest.name` for diagnostics."""
+
+    env_vars: list[AppliedEnvVar] = Field(default_factory=list)
+    templates: list[AppliedTemplate] = Field(default_factory=list)
+    config_block_applied: bool = False
+    """Whether the deep-merge into `agentforge.yaml` landed. Used by
+    `remove` to know whether to attempt the reverse merge."""