agentforge-core 0.3.0__tar.gz → 0.4.0__tar.gz

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentforge-core
-Version: 0.3.0
+Version: 0.4.0
 Summary: AgentForge core — stable contracts (ABCs, value types) for the agentic framework
 Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
 Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/pyproject.toml

@@ -9,7 +9,7 @@
 
 [project]
 name = "agentforge-core"
-version = "0.3.0"
+version = "0.4.0"
 description = "AgentForge core — stable contracts (ABCs, value types) for the agentic framework"
 readme = "README.md"
 requires-python = ">=3.13"

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/src/agentforge_core/__init__.py

@@ -11,6 +11,11 @@ the public surface for granular imports.
 
 from __future__ import annotations
 
+# Version is sourced from the installed distribution metadata so it can
+# never drift from pyproject.toml (bug-024).
+from importlib.metadata import PackageNotFoundError as _PkgNotFound
+from importlib.metadata import version as _dist_version
+
 from agentforge_core.config import (
     AgentConfig,
     AgentForgeConfig,
@@ -126,7 +131,10 @@ from agentforge_core.values import (
     VectorMatch,
 )
 
-__version__ = "0.2.3"
+try:
+    __version__ = _dist_version("agentforge-core")
+except _PkgNotFound:  # pragma: no cover - source tree without installed metadata
+    __version__ = "0.0.0+unknown"
 
 __all__ = [
     "OBSERVABILITY_SCOPE_NAME",

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/src/agentforge_core/config/schema.py

@@ -164,6 +164,10 @@ class GraphExpansionConfig(BaseModel):
     """Edge-type filter. YAML lists deserialize to `list[str]`;
     converted to a tuple by `build_retriever_from_config` before
     constructing the `GraphExpansion` value."""
+    direction: Literal["out", "in", "any"] = "any"
+    """Edge direction to follow during expansion (enh-005): `out`
+    (callees / what-X-cites), `in` (callers / who-cites-X), or `any`
+    (default — the original undirected `traverse` behaviour)."""
     text_property: str = "text"
     decay: float = Field(default=0.5, gt=0.0, le=1.0)
 
@@ -456,6 +460,34 @@ class OutputConfig(BaseModel):
     thresholds: dict[str, list[str]] = Field(default_factory=dict)
 
 
+class IdentityConfig(BaseModel):
+    """`governance.identity:` — the agent's identity (feat-029).
+
+    `provider` resolves against the `identity_providers` entry-point
+    category; `name` / `owner` / `attributes` describe the principal the
+    framework issues for this agent; `config` is provider-specific (issuer
+    URL, trust domain, role_arn, …)."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    provider: str = "local"
+    name: str | None = None
+    owner: str | None = None
+    attributes: dict[str, str] = Field(default_factory=dict)
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class GovernanceConfig(BaseModel):
+    """`governance:` — the governance spine (feat-029+).
+
+    Identity ships first; `registry` / `policy` / `audit` sub-blocks are
+    added as those pillars land."""
+
+    model_config = ConfigDict(strict=True, extra="forbid")
+
+    identity: IdentityConfig | None = None
+
+
 class AgentForgeConfig(BaseModel):
     """Root model — `agentforge.yaml` shape.
 
@@ -472,6 +504,7 @@ class AgentForgeConfig(BaseModel):
     logging: LoggingConfig = Field(default_factory=LoggingConfig)
     output: OutputConfig = Field(default_factory=OutputConfig)
     guardrail_policy: GuardrailPolicy = Field(default_factory=GuardrailPolicy)
+    governance: GovernanceConfig = Field(default_factory=GovernanceConfig)
     app: dict[str, Any] = Field(default_factory=dict)
     """Reserved namespace for **application** config (enh-002, feat-026
     Phase 1). The framework accepts this subtree but does not interpret

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/src/agentforge_core/contracts/__init__.py

@@ -13,6 +13,7 @@ from agentforge_core.contracts.embedding import EmbeddingClient
 from agentforge_core.contracts.evaluator import EvalResult, Evaluator
 from agentforge_core.contracts.finding import Finding
 from agentforge_core.contracts.graph_store import GraphStore
+from agentforge_core.contracts.identity import IdentityError, IdentityProvider
 from agentforge_core.contracts.llm import LLMClient
 from agentforge_core.contracts.memory import MemoryStore
 from agentforge_core.contracts.migrator import (
@@ -38,6 +39,8 @@ __all__ = [
     "FindingRenderer",
     "GraphStore",
     "HistoryTruncationStrategy",
+    "IdentityError",
+    "IdentityProvider",
     "LLMClient",
     "MemoryStore",
     "Migration",

agentforge_core-0.4.0/src/agentforge_core/contracts/identity.py

@@ -0,0 +1,88 @@
+"""`IdentityProvider` — locked governance-identity contract (feat-029).
+
+Every agent (and the tools / services it speaks to) gets a stable, portable
+`Principal` so every action has a name. A provider:
+
+- **issues** a principal for an agent from its declared name + owner,
+- **resolves** a principal by id,
+- **verifies** an inbound credential into a principal (prove who's calling),
+- mints an outbound **credential** for a principal (prove who we are),
+- **rotates** a principal's credential.
+
+Per ADR-0007 the methods on this ABC are locked once the feature ships;
+adding a method is a major-version bump. Optional behaviour goes behind
+`capabilities()` / `supports()`.
+
+The contract is vendor-neutral by construction: the `local` driver is
+self-contained and offline (deterministic, no network); OIDC / SPIFFE /
+cloud-IAM drivers map onto the same surface without the framework taking a
+hard dependency on any of them.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+
+from agentforge_core.values.auth import Principal
+
+
+class IdentityError(ValueError):
+    """Raised when a credential cannot be verified into a principal, or a
+    principal cannot be resolved for an operation that requires one."""
+
+
+class IdentityProvider(ABC):
+    """Issues, resolves, verifies, and rotates `Principal` identities."""
+
+    @abstractmethod
+    async def issue(
+        self,
+        *,
+        name: str,
+        owner: str,
+        attributes: Mapping[str, str] | None = None,
+    ) -> Principal:
+        """Mint (or return the existing) principal for an agent.
+
+        `name` is the agent's logical name; `owner` the accountable team /
+        human; `attributes` free-form string tags (env, region, …). The
+        returned `Principal.id` is stable across calls for the same
+        `name` (idempotent issue)."""
+
+    @abstractmethod
+    async def resolve(self, principal_id: str) -> Principal | None:
+        """Return the principal with this id, or ``None`` if unknown."""
+
+    @abstractmethod
+    async def verify(self, token: str) -> Principal:
+        """Verify an inbound credential and return its principal.
+
+        Raises:
+            IdentityError: the token is missing, malformed, expired, or
+                not issued by this provider.
+        """
+
+    @abstractmethod
+    async def credential(self, principal: Principal) -> str:
+        """Mint an outbound credential (token / assertion) that another
+        party can `verify()` back into `principal`."""
+
+    @abstractmethod
+    async def rotate(self, principal_id: str) -> Principal:
+        """Rotate the principal's signing material / credential. The
+        principal id is unchanged; previously minted credentials stop
+        verifying.
+
+        Raises:
+            IdentityError: `principal_id` is unknown.
+        """
+
+    def capabilities(self) -> set[str]:
+        """Optional capabilities this provider honours, from a closed
+        vocabulary (e.g. ``"rotation"``, ``"oidc"``, ``"spiffe"``).
+        Default: none."""
+        return set()
+
+    def supports(self, capability: str) -> bool:
+        return capability in self.capabilities()

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/src/agentforge_core/testing/__init__.py

@@ -17,6 +17,7 @@ from agentforge_core.testing.conformance import (
     run_embedding_conformance,
     run_graph_conformance,
     run_hybrid_search_conformance,
+    run_identity_conformance,
     run_input_validator_conformance,
     run_memory_conformance,
     run_output_validator_conformance,
@@ -33,6 +34,7 @@ __all__ = [
     "run_embedding_conformance",
     "run_graph_conformance",
     "run_hybrid_search_conformance",
+    "run_identity_conformance",
     "run_input_validator_conformance",
     "run_memory_conformance",
     "run_output_validator_conformance",

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/src/agentforge_core/testing/conformance.py

@@ -32,6 +32,7 @@ from agentforge_core.contracts.guardrails import (
     OutputValidator,
     ToolCallGate,
 )
+from agentforge_core.contracts.identity import IdentityError, IdentityProvider
 from agentforge_core.contracts.memory import MemoryStore
 from agentforge_core.contracts.reranker import Reranker
 from agentforge_core.contracts.strategy import ReasoningStrategy
@@ -1162,3 +1163,74 @@ async def run_hybrid_search_conformance(store: VectorStore) -> None:
         )
     finally:
         await store.delete(["a", "b", "c"])
+
+
+# ----------------------------------------------------------------------
+# Identity (feat-029)
+# ----------------------------------------------------------------------
+
+
+async def run_identity_conformance(provider: IdentityProvider) -> None:
+    """Assert an `IdentityProvider` honours the locked contract.
+
+    The provider must start empty of the principals issued here. Covers
+    issue→resolve round-trip + idempotency, credential/verify round-trip,
+    rotation, and the unknown/invalid paths.
+    """
+    # 1. issue → resolve round-trip; issued fields are preserved.
+    p = await provider.issue(
+        name="invoice-reconciler",
+        owner="finance-platform",
+        attributes={"env": "prod"},
+    )
+    assert p.id, "issued principal must have a non-empty id"
+    assert p.owner == "finance-platform", "issue must preserve owner"
+    assert p.metadata.get("env") == "prod", "issue must preserve attributes"
+
+    resolved = await provider.resolve(p.id)
+    assert resolved is not None, "resolve must find an issued principal"
+    assert resolved.id == p.id, "resolve must return the same id"
+
+    # 2. issue is idempotent on name — same name → same id.
+    again = await provider.issue(name="invoice-reconciler", owner="finance-platform")
+    assert again.id == p.id, "issue must be idempotent on name (stable id)"
+
+    # 3. resolve of an unknown id returns None (no raise).
+    assert await provider.resolve("agentforge:agent:nobody@0") is None, (
+        "resolve of an unknown id must return None"
+    )
+
+    # 4. credential → verify round-trip yields the same principal.
+    token = await provider.credential(p)
+    assert isinstance(token, str), "credential must return a string"
+    assert token, "credential must return a non-empty token"
+    verified = await provider.verify(token)
+    assert verified.id == p.id, "verify(credential(p)) must round-trip to p"
+
+    # 5. verify of a bogus credential raises IdentityError.
+    raised = False
+    try:
+        await provider.verify("not-a-real-credential")
+    except IdentityError:
+        raised = True
+    assert raised, "verify of an invalid credential must raise IdentityError"
+
+    # 6. rotation keeps the id but invalidates prior credentials.
+    rotated = await provider.rotate(p.id)
+    assert rotated.id == p.id, "rotate must keep the principal id"
+    stale = False
+    try:
+        await provider.verify(token)
+    except IdentityError:
+        stale = True
+    assert stale, "a credential minted before rotate() must stop verifying"
+    fresh = await provider.credential(rotated)
+    assert (await provider.verify(fresh)).id == p.id, "post-rotation credential must verify"
+
+    # 7. rotate of an unknown principal raises IdentityError.
+    unknown = False
+    try:
+        await provider.rotate("agentforge:agent:nobody@0")
+    except IdentityError:
+        unknown = True
+    assert unknown, "rotate of an unknown principal must raise IdentityError"

agentforge_core-0.4.0/src/agentforge_core/values/auth.py

@@ -0,0 +1,36 @@
+"""Auth value types (feat-014; widened by feat-029).
+
+`Principal` is the identity carried through the framework — returned by an
+`AuthPolicy` after a successful authentication (feat-014) and issued /
+resolved by an `IdentityProvider` (feat-029, governance identity). It
+carries an opaque ``id`` (the token itself by default; a stable URN once a
+real identity provider is wired — e.g.
+``agentforge:agent:<org>/<name>@<version>``) plus optional ``kind`` /
+``owner`` and a free-form ``metadata`` attribute bag (role tags, tenant
+id, env, region, …).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Identity returned by `AuthPolicy.authenticate(...)` and issued /
+    resolved by `IdentityProvider` (feat-029).
+
+    Attributes:
+        id: Stable identifier — a bearer token for env-backed auth, or a
+            URN for a governance identity provider.
+        kind: What the principal *is* — ``"agent"`` (default), ``"tool"``,
+            ``"service"``, or ``"human"``.
+        owner: The team / human accountable for the principal, if known.
+        metadata: Free-form string attributes (env, region, role tags,
+            tenant id) — the governance ``attributes`` bag.
+    """
+
+    id: str
+    kind: str = "agent"
+    owner: str | None = None
+    metadata: dict[str, str] = field(default_factory=dict)

{agentforge_core-0.3.0 → agentforge_core-0.4.0}/src/agentforge_core/values/retrieval.py

@@ -13,6 +13,8 @@ Pydantic model.
 
 from __future__ import annotations
 
+from typing import Literal
+
 from pydantic import BaseModel, ConfigDict, Field
 
 from agentforge_core.contracts.graph_store import GraphStore
@@ -32,6 +34,11 @@ class GraphExpansion(BaseModel):
             fan-out — tune cautiously.
         edge_types: If set, restricts traversal to these edge
             types. ``None`` means all edge types.
+        direction: Which way to follow edges during expansion
+            (enh-005). ``"out"`` follows ``src → dst`` (e.g.
+            callees, what-X-cites); ``"in"`` follows ``dst → src``
+            (e.g. callers, who-cites-X); ``"any"`` (default) is the
+            original undirected behaviour via ``store.traverse``.
         text_property: Graph-node property used to populate the
             synthesised ``VectorMatch.text``. Defaults to
             ``"text"``.
@@ -49,5 +56,6 @@ class GraphExpansion(BaseModel):
     store: GraphStore
     max_hops: int = Field(default=2, ge=1)
     edge_types: tuple[str, ...] | None = None
+    direction: Literal["out", "in", "any"] = "any"
     text_property: str = Field(default="text", min_length=1)
     decay: float = Field(default=0.5, gt=0.0, le=1.0)

agentforge_core-0.3.0/src/agentforge_core/values/auth.py

@@ -1,20 +0,0 @@
-"""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)