spec-agents-core 0.5.1__tar.gz

spec_agents_core-0.5.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dags/
+*.egg-info/
+examples/output/
+build/
+.coverage
+coverage.xml

spec_agents_core-0.5.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## [0.5.1](https://github.com/marcionicolau/spec-agents/compare/agent-fabric-v0.5.0...agent-fabric-v0.5.1) (2026-10-02)
+
+
+### Bug Fixes
+
+* document the spec-agents-* distribution names in the package READMEs ([#96](https://github.com/marcionicolau/spec-agents/issues/96)) ([fffad88](https://github.com/marcionicolau/spec-agents/commit/fffad88e5c8405bb01c7d9dddf66b7cf52a13e28)), closes [#76](https://github.com/marcionicolau/spec-agents/issues/76)
+
+## [0.5.0](https://github.com/marcionicolau/spec-agents/compare/agent-fabric-v0.4.0...agent-fabric-v0.5.0) (2026-10-02)
+
+
+### Features
+
+* **agent-fabric:** core/pack API level contract ([#75](https://github.com/marcionicolau/spec-agents/issues/75)) ([d880a74](https://github.com/marcionicolau/spec-agents/commit/d880a744481b888e1e435a1c0d482e44fa942e03)), closes [#20](https://github.com/marcionicolau/spec-agents/issues/20)
+* **agent-fabric:** define the public API surface with __all__, fix __version__ ([#57](https://github.com/marcionicolau/spec-agents/issues/57)) ([c9ab564](https://github.com/marcionicolau/spec-agents/commit/c9ab56432fb2e95c5f1a1ebd9428a23c42b9d89f)), closes [#56](https://github.com/marcionicolau/spec-agents/issues/56)
+
+## [0.4.0](https://github.com/marcionicolau/spec-agents/compare/agent-fabric-v0.3.0...agent-fabric-v0.4.0) (2026-10-01)
+
+
+### Features
+
+* **agent-fabric:** export skills as spec-compliant Agent Skills ([#54](https://github.com/marcionicolau/spec-agents/issues/54)) ([bb2b9bb](https://github.com/marcionicolau/spec-agents/commit/bb2b9bbf395bb90107a8bdcb47aad5516d0aadab)), closes [#22](https://github.com/marcionicolau/spec-agents/issues/22)
+
+## [0.3.0](https://github.com/marcionicolau/spec-agents/compare/agent-fabric-v0.2.0...agent-fabric-v0.3.0) (2026-10-01)
+
+
+### Features
+
+* **agent-fabric:** gate deterministic eval suites on stored baselines ([#52](https://github.com/marcionicolau/spec-agents/issues/52)) ([378b2fd](https://github.com/marcionicolau/spec-agents/commit/378b2fdbed74a0213dc142720ae05c0a17525b6f)), closes [#24](https://github.com/marcionicolau/spec-agents/issues/24)
+
+## [0.2.0](https://github.com/marcionicolau/spec-agents/compare/agent-fabric-v0.1.0...agent-fabric-v0.2.0) (2026-10-01)
+
+
+### Features
+
+* **agent-fabric:** fail PRs whose SKILL.md contract changes lack a version bump ([#51](https://github.com/marcionicolau/spec-agents/issues/51)) ([ac97619](https://github.com/marcionicolau/spec-agents/commit/ac97619390756378cb1b8cdd9145814a93417ba0))
+* **agent-fabric:** lint skill descriptions for what-and-when style ([#49](https://github.com/marcionicolau/spec-agents/issues/49)) ([321a834](https://github.com/marcionicolau/spec-agents/commit/321a8343fa8f8953a7bea7974841858015e9c890)), closes [#23](https://github.com/marcionicolau/spec-agents/issues/23)
+
+## [0.1.0](https://github.com/marcionicolau/spec-agents/compare/agent-fabric-v0.0.1...agent-fabric-v0.1.0) (2026-10-01)
+
+
+### Features
+
+* **agent-fabric:** enforce architecture boundaries and type-check the core; fix live view crash ([#38](https://github.com/marcionicolau/spec-agents/issues/38)) ([45b277f](https://github.com/marcionicolau/spec-agents/commit/45b277f586b14bf966d13f3eaacb66df52f5649b))
+
+
+### Bug Fixes
+
+* **statistics:** warn on perfect collinearity with inf VIF; ci: require lowest-versions job ([#35](https://github.com/marcionicolau/spec-agents/issues/35)) ([e1502a1](https://github.com/marcionicolau/spec-agents/commit/e1502a1a7d0cfb65dd65e6087843ae6bddc4a378))

spec_agents_core-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcio Nicolau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spec_agents_core-0.5.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: spec-agents-core
+Version: 0.5.1
+Summary: Spec-driven pipelines and hierarchical agents (PydanticAI, DSPy, CrewAI, LangChain) over a LiteLLM proxy
+Project-URL: Homepage, https://github.com/marcionicolau/spec-agents
+Project-URL: Repository, https://github.com/marcionicolau/spec-agents
+Project-URL: Issues, https://github.com/marcionicolau/spec-agents/issues
+Project-URL: Changelog, https://github.com/marcionicolau/spec-agents/blob/main/packages/agent-fabric/CHANGELOG.md
+Project-URL: Documentation, https://github.com/marcionicolau/spec-agents/tree/main/docs
+Author: Marcio Nicolau
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llm,pipelines,pydantic,specs
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.7.1
+Provides-Extra: all
+Requires-Dist: crewai>=0.100; extra == 'all'
+Requires-Dist: dspy>=3.0; extra == 'all'
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: pandas>=2.1; extra == 'all'
+Requires-Dist: pydantic-ai-slim[openai]>=1.0; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == 'crewai'
+Provides-Extra: dspy
+Requires-Dist: dspy>=3.0; extra == 'dspy'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: proxy
+Requires-Dist: litellm[proxy]>=1.60; extra == 'proxy'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim[openai]>=1.0; extra == 'pydantic-ai'
+Provides-Extra: tabular
+Requires-Dist: pandas>=2.1; extra == 'tabular'
+Description-Content-Type: text/markdown
+
+# spec-agents-core (`agent_fabric`)
+
+Domain-agnostic core for **spec-driven pipelines and hierarchical agents**. Components, pipelines and agents are declared in Markdown
+with YAML frontmatter (`SKILL.md`, `AGENT.md`, `fabric.md`); the frontmatter is a contract validated by Pydantic and the body is guidance
+injected into prompts on demand. LLMs plan, delegate, repair and interpret — **they never compute**: every result comes from
+deterministic `Component.compute()` code run by the `PipelineExecutor`.
+
+> **Status:** pre-release. Until the first PyPI release, install a wheel from the
+> [GitHub Releases](https://github.com/marcionicolau/spec-agents/releases) or use `uv sync --all-packages` in a checkout;
+> the `pip install` lines below are the PyPI names.
+
+## Names
+
+| | |
+| --- | --- |
+| PyPI distribution | `spec-agents-core` |
+| Import name | `agent_fabric` |
+| Directory in the monorepo | `packages/agent-fabric` |
+| Release tag / PR scope | `agent-fabric-vX.Y.Z` / `agent-fabric` |
+
+The distribution is named `spec-agents-core` because the shorter names are taken on PyPI; the import name and the entry point do not change.
+
+## Install
+```bash
+pip install spec-agents-core                  # core: pydantic, numpy, pyyaml, rich (import name: agent_fabric)
+pip install "spec-agents-core[tabular]"       # + pandas (dataframe artifact types)
+pip install "spec-agents-core[all]"           # + PydanticAI, DSPy, CrewAI, LangChain adapters
+```
+Domain packs ([statistics](../statistics/README.md), [lakehouse](../lakehouse/README.md), [coworker](../coworker/README.md),
+[text-pack](../text-pack/README.md)) register themselves through the `agent_fabric.domains` entry point.
+
+## Use
+```bash
+agent-fabric catalog --skills path/to/skills     # list components and pipelines
+agent-fabric agents path/to/config               # render and validate an agent tree
+agent-fabric lint --agents path/to/config --strict
+agent-fabric run path/to/config "task" --input name=file.txt
+```
+```python
+from agent_fabric import build_registry
+from agent_fabric.agents import AgentFabric, AgentsConfig
+
+fabric = AgentFabric(build_registry(discover=True), AgentsConfig.load("config"))
+report = fabric.run("question", {"data": df}, session_id="s1")
+```
+
+Optional frameworks are imported lazily; models are referenced by LiteLLM alias only. See the repository
+[docs](../../docs/README.md) for the architecture, the error model and how to add components, pipelines and agents.

spec_agents_core-0.5.1/README.md

@@ -0,0 +1,48 @@
+# spec-agents-core (`agent_fabric`)
+
+Domain-agnostic core for **spec-driven pipelines and hierarchical agents**. Components, pipelines and agents are declared in Markdown
+with YAML frontmatter (`SKILL.md`, `AGENT.md`, `fabric.md`); the frontmatter is a contract validated by Pydantic and the body is guidance
+injected into prompts on demand. LLMs plan, delegate, repair and interpret — **they never compute**: every result comes from
+deterministic `Component.compute()` code run by the `PipelineExecutor`.
+
+> **Status:** pre-release. Until the first PyPI release, install a wheel from the
+> [GitHub Releases](https://github.com/marcionicolau/spec-agents/releases) or use `uv sync --all-packages` in a checkout;
+> the `pip install` lines below are the PyPI names.
+
+## Names
+
+| | |
+| --- | --- |
+| PyPI distribution | `spec-agents-core` |
+| Import name | `agent_fabric` |
+| Directory in the monorepo | `packages/agent-fabric` |
+| Release tag / PR scope | `agent-fabric-vX.Y.Z` / `agent-fabric` |
+
+The distribution is named `spec-agents-core` because the shorter names are taken on PyPI; the import name and the entry point do not change.
+
+## Install
+```bash
+pip install spec-agents-core                  # core: pydantic, numpy, pyyaml, rich (import name: agent_fabric)
+pip install "spec-agents-core[tabular]"       # + pandas (dataframe artifact types)
+pip install "spec-agents-core[all]"           # + PydanticAI, DSPy, CrewAI, LangChain adapters
+```
+Domain packs ([statistics](../statistics/README.md), [lakehouse](../lakehouse/README.md), [coworker](../coworker/README.md),
+[text-pack](../text-pack/README.md)) register themselves through the `agent_fabric.domains` entry point.
+
+## Use
+```bash
+agent-fabric catalog --skills path/to/skills     # list components and pipelines
+agent-fabric agents path/to/config               # render and validate an agent tree
+agent-fabric lint --agents path/to/config --strict
+agent-fabric run path/to/config "task" --input name=file.txt
+```
+```python
+from agent_fabric import build_registry
+from agent_fabric.agents import AgentFabric, AgentsConfig
+
+fabric = AgentFabric(build_registry(discover=True), AgentsConfig.load("config"))
+report = fabric.run("question", {"data": df}, session_id="s1")
+```
+
+Optional frameworks are imported lazily; models are referenced by LiteLLM alias only. See the repository
+[docs](../../docs/README.md) for the architecture, the error model and how to add components, pipelines and agents.

spec_agents_core-0.5.1/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "spec-agents-core"
+dynamic = ["version"]
+description = "Spec-driven pipelines and hierarchical agents (PydanticAI, DSPy, CrewAI, LangChain) over a LiteLLM proxy"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "Marcio Nicolau" }]
+keywords = ["agents", "llm", "pipelines", "specs", "pydantic"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "numpy>=1.26",
+  "pydantic>=2.7",
+  "pyyaml>=6.0.2",
+  "rich>=13.7.1",
+]
+
+[project.scripts]
+agent-fabric = "agent_fabric.cli:main"
+
+[project.optional-dependencies]
+all = ["spec-agents-core[tabular,pydantic-ai,dspy,crewai,langchain]"]
+crewai = ["crewai>=0.100"]
+dspy = ["dspy>=3.0"]
+langchain = ["langchain-core>=0.3"]
+proxy = ["litellm[proxy]>=1.60"]
+pydantic-ai = ["pydantic-ai-slim[openai]>=1.0"]
+tabular = ["pandas>=2.1"]
+
+[project.urls]
+Homepage = "https://github.com/marcionicolau/spec-agents"
+Repository = "https://github.com/marcionicolau/spec-agents"
+Issues = "https://github.com/marcionicolau/spec-agents/issues"
+Changelog = "https://github.com/marcionicolau/spec-agents/blob/main/packages/agent-fabric/CHANGELOG.md"
+Documentation = "https://github.com/marcionicolau/spec-agents/tree/main/docs"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.14"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = true
+
+# version = latest "agent-fabric-vX.Y.Z" git tag (other packages' tags are ignored); untagged commits get X.Y.(Z+1).devN+<sha>
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_fabric"]
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+pattern-prefix = "agent-fabric-"
+fallback-version = "0.0.0"

spec_agents_core-0.5.1/src/agent_fabric/__init__.py

@@ -0,0 +1,55 @@
+"""agent_fabric - spec-driven pipelines and hierarchical agents over a LiteLLM proxy."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version(
+        "spec-agents-core"
+    )  # dynamic: derived from the latest agent-fabric-v* git tag at build time
+except _metadata.PackageNotFoundError:  # pragma: no cover - source tree without an installed distribution
+    __version__ = "0.0.0"
+
+
+def domain_loader(ref: str) -> Callable:
+    """Resolve a domain reference: 'module:register' callable, or an existing directory
+    loaded as a code-free spec pack (skills/<name>/SKILL.md, no Python required)."""
+    from pathlib import Path
+
+    p = Path(ref)
+    if ":" not in ref and p.is_dir():
+        return lambda reg: reg.load_domain(p)
+    import importlib
+
+    mod, _, attr = ref.partition(":")
+    return getattr(importlib.import_module(mod), attr or "register")
+
+
+def build_registry(domains: Iterable[Callable | str] = (), discover: bool = False):
+    """Create a Registry and load domain packs (callables ``register(registry)`` or
+    references resolved by :func:`domain_loader`)."""
+    from .compat import check_pack_api
+    from .registry import Registry
+
+    reg = Registry()
+    for d in domains:
+        register = d if callable(d) else domain_loader(d)
+        check_pack_api(register, d if isinstance(d, str) else getattr(d, "__module__", repr(d)))
+        register(reg)
+    if discover:
+        reg.discover_domains()
+    return reg
+
+
+from .compat import API_LEVEL, API_LEVEL_MIN, requires_api  # noqa: E402
+
+__all__ = [
+    "API_LEVEL",
+    "API_LEVEL_MIN",
+    "__version__",
+    "build_registry",
+    "domain_loader",
+    "requires_api",
+]

spec_agents_core-0.5.1/src/agent_fabric/agents/__init__.py

@@ -0,0 +1,39 @@
+"""Hierarchical agents: declared as a tree in YAML, validated as a whole, built by registered builders."""
+
+from .base import BaseAgent
+from .fabric import AgentFabric, planner_builder
+from .kinds import (
+    Delegation,
+    DelegationPlan,
+    FunctionAgent,
+    LLMWorkerAgent,
+    PipelineAgent,
+    PlannerAgent,
+    PydanticAISupervisor,
+    SupervisorAgent,
+)
+from .runtime import AgentResult, AgentRunReport, AgentTask, Budget, BudgetSettings, RunContext, TraceEvent
+from .spec import AgentsConfig, AgentSpec
+
+__all__ = [
+    "AgentFabric",
+    "AgentResult",
+    "AgentRunReport",
+    "AgentSpec",
+    "AgentTask",
+    "AgentsConfig",
+    "BaseAgent",
+    "Budget",
+    "BudgetSettings",
+    "Delegation",
+    "DelegationPlan",
+    "FunctionAgent",
+    "LLMWorkerAgent",
+    "PipelineAgent",
+    "PlannerAgent",
+    "PydanticAISupervisor",
+    "RunContext",
+    "SupervisorAgent",
+    "TraceEvent",
+    "planner_builder",
+]

spec_agents_core-0.5.1/src/agent_fabric/agents/base.py

@@ -0,0 +1,155 @@
+"""Base agent: template method shared by every kind (budget, trace, fallback, memory)."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from ..errors import BudgetExceeded, FabricError
+from ..llm.backends import LLMSettings
+from ..llm.prompts import AGENT_SYSTEM, compact
+from ..memory.base import RunSummary, memory_context, namespaced
+from .runtime import AgentResult, AgentTask, MeteredBackend, RunContext, Status
+from .spec import AgentSpec
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .fabric import AgentFabric
+
+
+class BaseAgent(ABC):
+    accepts_sub_agents: bool = False
+
+    def __init__(
+        self, name: str, spec: AgentSpec, fabric: AgentFabric, children: dict[str, BaseAgent] | None = None
+    ) -> None:
+        self.name, self.spec, self.fabric = name, spec, fabric
+        self.children: dict[str, BaseAgent] = children or {}
+        self.fallback_agent: BaseAgent | None = None
+
+    # ------------------------------------------------------------------ template method
+    def run(self, task: AgentTask, ctx: RunContext, parent_path: str = "", depth: int = 0) -> AgentResult:
+        """Run the agent on a task: the template method every agent goes through.
+
+        Records the start and end events, charges the run budget (``max_depth`` and ``max_agent_runs``) and calls the kind-specific ``_run``. A
+        `BudgetExceeded` or other `FabricError` becomes a ``failed`` result carrying the located error; when a ``fallback`` backend is configured it is
+        tried first and the fallback is noted in ``notes``. Records LLM calls and duration, and, when memory is configured, the instruction, the answer and a
+        `RunSummary` under ``<session>/<path>``. Does not raise `FabricError`s: they end up in the result.
+        """
+        path = f"{parent_path}/{self.name}" if parent_path else self.name
+        t0 = time.perf_counter()
+        ctx.event(path, "start", task.instruction)
+        try:
+            ctx.budget.charge_run(path, depth)
+            res = self._run(task, ctx, path, depth)
+        except BudgetExceeded as exc:
+            res = self.result(path, "failed", error=exc.report, summary=exc.message)
+        except FabricError as exc:
+            ctx.event(path, "error", f"{exc.category.value}: {exc.message}")
+            if self.fallback_agent is None:
+                res = self.result(path, "failed", error=exc.report, summary=exc.message)
+            else:
+                ctx.event(path, "fallback", self.fallback_agent.spec.backend)
+                try:
+                    res = self.fallback_agent._run(task, ctx, path, depth)
+                    res.notes.append(
+                        f"fell back to backend '{self.fallback_agent.spec.backend}' after "
+                        f"{exc.category.value} error: {exc.message}"
+                    )
+                except FabricError as exc2:
+                    res = self.result(
+                        path,
+                        "failed",
+                        error=exc2.report,
+                        summary=exc2.message,
+                        notes=[f"primary failed: {exc.message}"],
+                    )
+        res.llm_calls = ctx.llm_calls_by_path.get(path, 0)
+        res.duration_s = round(time.perf_counter() - t0, 4)
+        ctx.event(path, "end", res.status)
+        if ctx.memory is not None:
+            ctx.memory.add_message(namespaced(ctx.session_id, path), "user", task.instruction)
+            ctx.memory.add_message(namespaced(ctx.session_id, path), "assistant", res.summary or res.status)
+            ctx.memory.remember_run(
+                namespaced(ctx.session_id, path),
+                RunSummary(
+                    objective=task.instruction, agent=path, status={path: res.status}, headlines=[res.summary[:200]]
+                ),
+            )
+        return res
+
+    @abstractmethod
+    def _run(self, task: AgentTask, ctx: RunContext, path: str, depth: int) -> AgentResult: ...
+
+    # ------------------------------------------------------------------ helpers
+    @property
+    def kind(self) -> str:
+        """The agent kind (``supervisor``, ``planner``, ``pipeline``, ``llm`` or ``function``)."""
+        return self.spec.kind
+
+    @property
+    def settings(self) -> LLMSettings:
+        """`LLMSettings` for this agent: the run's settings with the agent's own model, temperature and retries applied."""
+        return self.fabric.settings_for(self.spec)
+
+    @property
+    def model(self) -> str:
+        """LiteLLM alias this agent uses (its own ``model``, else the default for its kind)."""
+        return self.fabric.model_for(self.spec)
+
+    def llm(self, ctx: RunContext, path: str) -> MeteredBackend:
+        """The LLM backend for this agent, metered so every call is charged to the run budget and traced at ``path``."""
+        return ctx.metered(self.fabric.llm_backend, path)
+
+    def result(self, path: str, status: Status, **kw: Any) -> AgentResult:
+        """Build an `AgentResult` for this agent at ``path`` with the given status and extra fields."""
+        return AgentResult(agent=self.name, path=path, kind=self.kind, status=status, **kw)
+
+    def system_prompt(self) -> str:
+        """Role header (if any) followed by the AGENT.md body - the body is the primary instruction source."""
+        s = self.spec
+        parts = []
+        if s.role or s.goal:
+            parts.append(
+                AGENT_SYSTEM.format(
+                    role=s.role or self.name.replace("_", " "), goal=s.goal or s.card, backstory=s.backstory
+                ).strip()
+            )
+        if s.instructions:
+            parts.append(s.instructions)
+        return "\n\n".join(parts) or f"You are the '{self.name}' agent."
+
+    def input_keys(self, task: AgentTask, ctx: RunContext) -> list[str]:
+        """Blackboard keys this agent reads: the task's own inputs, else the spec's ``inputs``, else every key the run started with."""
+        return task.inputs or self.spec.inputs or list(ctx.input_keys)
+
+    def describe_inputs(self, values: dict[str, Any]) -> str:
+        """Describe input values for a prompt: JSON, number and ``any`` values are shown compacted (up to 2500 characters), other types through their artifact profile."""
+        types = self.fabric.registry.types
+        lines = []
+        for key, v in values.items():
+            t = types.infer(v)
+            if t.name in ("json", "any", "number"):
+                lines.append(f"[{key}] {compact(v, max_chars=2500)}")
+            else:
+                lines.append(f"[{key}] {t.describe(t.profile(v), v)}")
+        return "\n".join(lines) or "(none)"
+
+    def memory_context(self, ctx: RunContext, path: str) -> str:
+        """Text of this agent's recent runs in the session, for routers and planners."""
+        return memory_context(ctx.memory, namespaced(ctx.session_id, path))
+
+    def card(self) -> dict[str, Any]:
+        """Short description of the agent for parent routers: name, kind, role, what it does and, for supervisors, its sub-agents."""
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "role": self.spec.role,
+            "does": self.spec.card,
+            **({"sub_agents": sorted(self.children)} if self.children else {}),
+        }
+
+
+__all__ = [
+    "BaseAgent",
+]