agentic-fabric 1.2.0__py3-none-any.whl

agentic_fabric/__init__.py

@@ -0,0 +1,90 @@
+"""agentic-fabric: Framework-agnostic AI fabric orchestration.
+
+Declare fabric agents once, run on CrewAI, LangGraph, or Strands.
+
+Usage:
+    from agentic_fabric.core.decomposer import run_fabric_agent_auto, get_runner, detect_framework
+    from agentic_fabric.core.discovery import discover_packages, get_fabric_agent_config
+    from agentic_fabric.core.manager import ManagerAgent
+
+    # Auto-detect framework and run a fabric agent
+    packages = discover_packages()
+    config = get_fabric_agent_config(packages["my-package"], "reviewer")
+    result = run_fabric_agent_auto(config, inputs={"task": "..."})
+
+    # Or get a specific runner
+    runner = get_runner("crewai")  # or "langgraph", "strands"
+    fabric_agent = runner.build_fabric_agent(config)
+    result = runner.run(fabric_agent, inputs)
+
+    # Or use a hierarchical manager agent
+    class MyManager(ManagerAgent):
+        def __init__(self):
+            super().__init__(fabric_agents={
+                "design": "design_review",
+                "implementation": "implementation_review"
+            })
+
+        async def execute_workflow(self, task):
+            design = await self.delegate_async("design", task)
+            return await self.delegate_async("implementation", design)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("agentic-fabric")
+except PackageNotFoundError:  # pragma: no cover - only hit when not installed
+    __version__ = "1.2.0"
+
+# Core exports - framework-agnostic functionality
+from agentic_fabric.agentic_data import AgenticData
+from agentic_fabric.capabilities import (
+    AgentCapabilityProviderMixin,
+    AgentCapabilitySpec,
+    agent_capability,
+    runtime_capability,
+    tool_capability,
+)
+from agentic_fabric.core.decomposer import (
+    compose_fabric_agent,
+    detect_framework,
+    get_available_frameworks,
+    get_framework_info,
+    get_runner,
+    is_framework_available,
+    run_fabric_agent_auto,
+)
+from agentic_fabric.core.discovery import (
+    discover_all_framework_configs,
+    discover_packages,
+    get_fabric_agent_config,
+    list_fabric_agents,
+)
+from agentic_fabric.core.manager import ManagerAgent
+
+
+__all__ = [
+    "AgentCapabilityProviderMixin",
+    "AgentCapabilitySpec",
+    "AgenticData",
+    "ManagerAgent",
+    "__version__",
+    "agent_capability",
+    "compose_fabric_agent",
+    "detect_framework",
+    "discover_all_framework_configs",
+    "discover_packages",
+    "get_available_frameworks",
+    "get_fabric_agent_config",
+    "get_framework_info",
+    "get_runner",
+    "is_framework_available",
+    "list_fabric_agents",
+    "run_fabric_agent_auto",
+    "runtime_capability",
+    "tool_capability",
+]

agentic_fabric/__main__.py

@@ -0,0 +1,9 @@
+"""Allow running as: python -m agentic_fabric."""
+
+from __future__ import annotations
+
+from agentic_fabric.main import main
+
+
+if __name__ == "__main__":
+    main()

agentic_fabric/agentic_data.py

@@ -0,0 +1,284 @@
+"""Agent runtime facade over the vendor and data layers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, ClassVar
+
+from agentic_fabric.runners.registry import RuntimeUnavailableError, install_command, runtime_info, runtime_names
+
+
+try:  # pragma: no cover - exercised when vendor-fabric is installed by consumers
+    from vendor_fabric.vendor_data import VendorData as _VendorDataBase
+except ImportError:  # pragma: no cover - default in this workspace until vendor-fabric is published
+    _VENDOR_FABRIC_AVAILABLE = False
+
+    class _VendorDataBase:  # type: ignore[no-redef]
+        """Small fallback that keeps AgenticData importable without vendor-fabric.
+
+        This is an importability shim, not a second architecture. It implements
+        the minimal ``VendorData`` surface needed for ``AgenticData`` to function.
+        Methods that require vendor-fabric raise clear ``ImportError`` guidance.
+
+        Omitted vs. real ``VendorData``: ``capabilities()`` returns an empty list
+        (so ``vendor_tools()`` degrades gracefully instead of crashing).
+        """
+
+        def __init__(self, value: Any = None, *, fabric: Any = None, logger: Any = None, **_: Any) -> None:
+            self._agentic_value = value
+            self._active_provider: str | None = None
+            self._logger = logger
+
+        @property
+        def value(self) -> Any:
+            """Return the wrapped value."""
+            return self._agentic_value
+
+        @property
+        def active_provider(self) -> str | None:
+            """Return the active vendor provider, when available."""
+            return self._active_provider
+
+        def as_builtin(self) -> Any:
+            """Return the wrapped value unchanged."""
+            return self._agentic_value
+
+        def cast(self, value: Any) -> _VendorDataBase:
+            """Replace the wrapped value."""
+            self._agentic_value = value
+            return self
+
+        def open(self, provider_id: str, *, strict: bool = True, **_: Any) -> _VendorDataBase:
+            """Record a provider or raise install guidance when strict."""
+            if strict:
+                msg = (
+                    f"Provider '{provider_id}' requires vendor-fabric. "
+                    "Install vendor-fabric after it is published, then reinstall agentic-fabric."
+                )
+                raise ImportError(msg)
+            self._active_provider = provider_id
+            return self
+
+        def call(self, operation: str, *_: Any, **__: Any) -> Any:
+            """Raise clear guidance for vendor-backed operations."""
+            msg = f"Vendor operation '{operation}' requires vendor-fabric."
+            raise ImportError(msg)
+
+        def capabilities(self, provider: str | None = None, *, include_unavailable: bool = True) -> list[Any]:
+            """Return an empty capability list without vendor-fabric.
+
+            Without vendor-fabric, no provider capabilities are available.
+            This lets ``vendor_tools()`` degrade gracefully (returns ``[]``).
+            """
+            return []
+
+else:
+    _VENDOR_FABRIC_AVAILABLE = True
+
+
+class AgenticData(_VendorDataBase):
+    """VendorData extension with active runtime and fabric agent registry context."""
+
+    runtime_priority: ClassVar[tuple[str, ...]] = tuple(runtime_names())
+
+    def __init__(
+        self,
+        value: Any = None,
+        *,
+        fabric: Any | None = None,
+        fabric_agents: Mapping[str, Mapping[str, Any]] | None = None,
+        logger: Any | None = None,
+        active_runtime: str | None = None,
+        **fabric_kwargs: Any,
+    ) -> None:
+        """Initialize data, registered fabric agents, and optional active runtime."""
+        super().__init__(value, fabric=fabric, logger=logger, **fabric_kwargs)
+        self._fabric_agents: dict[str, dict[str, Any]] = {
+            name: dict(config) for name, config in (fabric_agents or {}).items()
+        }
+        self._active_runtime: str | None = None
+        if active_runtime is not None:
+            self.use_runtime(active_runtime, strict=False)
+
+    @property
+    def fabric_agents(self) -> Mapping[str, Mapping[str, Any]]:
+        """Return registered fabric agent definitions."""
+        return MappingProxyType(self._fabric_agents)
+
+    @property
+    def active_runtime(self) -> str | None:
+        """Return the active runtime name, when one has been selected."""
+        return self._active_runtime
+
+    @property
+    def vendor_fabric_available(self) -> bool:
+        """Return whether this import is backed by a real VendorData class."""
+        return _VENDOR_FABRIC_AVAILABLE
+
+    def cast(self, value: Any) -> AgenticData:
+        """Mutate the wrapped data while preserving runtime context."""
+        super().cast(value)
+        return self
+
+    def register_fabric_agent(self, name: str, fabric_agent_config: Mapping[str, Any]) -> AgenticData:
+        """Register a named fabric agent config for ``run_fabric_agent`` lookup."""
+        self._fabric_agents[name] = dict(fabric_agent_config)
+        return self
+
+    def unregister_fabric_agent(self, name: str) -> AgenticData:
+        """Remove a named fabric agent config if it exists."""
+        self._fabric_agents.pop(name, None)
+        return self
+
+    def use_runtime(self, runtime: str, *, strict: bool = True) -> AgenticData:
+        """Select the active runtime for future agent calls."""
+        normalized = runtime.strip().lower()
+        if normalized == "auto":
+            normalized = self.select_runtime()
+        if strict and not self.is_runtime_available(normalized):
+            raise RuntimeUnavailableError(normalized, install_command(normalized))
+        self._active_runtime = normalized
+        return self
+
+    def clear_runtime(self) -> AgenticData:
+        """Clear the active runtime selection."""
+        self._active_runtime = None
+        return self
+
+    def runtimes(self) -> list[dict[str, Any]]:
+        """Return runtime registry metadata with availability."""
+        info = runtime_info()
+        return list(info) if isinstance(info, list) else [info]
+
+    def runtime_info(self, runtime: str | None = None) -> list[dict[str, Any]] | dict[str, Any]:
+        """Return runtime metadata with current availability."""
+        return runtime_info(runtime)
+
+    def is_runtime_available(self, runtime: str) -> bool:
+        """Return whether a runtime is importable in the current environment."""
+        from agentic_fabric.core.decomposer import is_framework_available
+
+        return is_framework_available(runtime)
+
+    def select_runtime(
+        self,
+        runtime: str | None = None,
+        *,
+        fabric_agent_config: Mapping[str, Any] | None = None,
+    ) -> str:
+        """Select a runtime using explicit, active, manifest, then auto priority."""
+        required_runtime = _manifest_runtime(fabric_agent_config)
+        requested = _normalize_runtime(runtime)
+        active = _normalize_runtime(self._active_runtime)
+
+        if requested is not None and required_runtime is not None and requested != required_runtime:
+            msg = f"Fabric agent requires {required_runtime} but {requested} was requested"
+            raise ValueError(msg)
+
+        if requested is not None:
+            return _require_available(requested)
+
+        if active is not None:
+            if required_runtime is not None and active != required_runtime:
+                msg = f"Active runtime {active} conflicts with fabric agent requirement {required_runtime}"
+                raise ValueError(msg)
+            return _require_available(active)
+
+        if required_runtime is not None:
+            return _require_available(required_runtime)
+
+        from agentic_fabric.core.decomposer import detect_framework
+
+        return detect_framework()
+
+    def run_fabric_agent(
+        self,
+        fabric_agent: str | Mapping[str, Any],
+        inputs: Mapping[str, Any] | None = None,
+        *,
+        runtime: str | None = None,
+        **input_kwargs: Any,
+    ) -> str:
+        """Run a registered fabric agent by name or a direct fabric agent config."""
+        from agentic_fabric.core.decomposer import run_fabric_agent_auto
+
+        fabric_agent_config = self._lookup_fabric_agent(fabric_agent)
+        merged_inputs = dict(inputs or {})
+        merged_inputs.update(input_kwargs)
+        selected_runtime = self.select_runtime(runtime, fabric_agent_config=fabric_agent_config)
+        return run_fabric_agent_auto(fabric_agent_config, inputs=merged_inputs, framework=selected_runtime)
+
+    def call_runtime(self, capability: str, *args: Any, runtime: str | None = None, **kwargs: Any) -> Any:
+        """Call a declared capability on a selected runtime runner."""
+        from agentic_fabric.core.decomposer import get_runner
+
+        selected_runtime = self.select_runtime(runtime)
+        runner = get_runner(selected_runtime)
+        return runner.call_capability(capability, *args, **kwargs)
+
+    def vendor_tools(
+        self,
+        provider: str | None = None,
+        *,
+        include_unavailable: bool = True,
+    ) -> list[Any]:
+        """Return agent-facing tools built from inherited vendor capabilities."""
+        from agentic_fabric.tools.vendor import vendor_capability_tools
+
+        return vendor_capability_tools(self, provider=provider, include_unavailable=include_unavailable)
+
+    def __getattr__(self, name: str) -> Any:
+        """Expose ``run_<fabric_agent>`` helpers while preserving VendorData dispatch."""
+        if name.startswith("run_"):
+            fabric_agent_name = name.removeprefix("run_")
+            if fabric_agent_name in self._fabric_agents:
+                return lambda *args, **kwargs: self.run_fabric_agent(fabric_agent_name, *args, **kwargs)
+
+        # When real VendorData is installed, it may define __getattr__ for
+        # provider dispatch. Try the superclass, but fall through to a clean
+        # AttributeError if neither this class nor the superclass handles it.
+        if hasattr(super(), "__getattr__"):
+            return super().__getattr__(name)  # type: ignore[misc]
+        raise AttributeError(f"{type(self).__name__!s} has no attribute {name!r}")
+
+    def __dir__(self) -> list[str]:
+        """Include dynamic registered-fabric-agent helpers in introspection."""
+        dynamic = [f"run_{name}" for name in self._fabric_agents]
+        return sorted({*super().__dir__(), *dynamic})
+
+    def _lookup_fabric_agent(self, fabric_agent: str | Mapping[str, Any]) -> dict[str, Any]:
+        """Return a fabric agent config from a name or direct mapping."""
+        if isinstance(fabric_agent, Mapping):
+            return dict(fabric_agent)
+        try:
+            return dict(self._fabric_agents[fabric_agent])
+        except KeyError as exc:
+            options = ", ".join(sorted(self._fabric_agents)) or "none registered"
+            msg = f"Unknown fabric agent '{fabric_agent}'. Registered fabric agents: {options}"
+            raise KeyError(msg) from exc
+
+
+def _normalize_runtime(runtime: str | None) -> str | None:
+    """Normalize runtime names and treat auto as no explicit choice."""
+    if runtime is None:
+        return None
+    normalized = runtime.strip().lower()
+    return None if normalized == "auto" else normalized
+
+
+def _manifest_runtime(fabric_agent_config: Mapping[str, Any] | None) -> str | None:
+    """Read runtime requirements from a fabric agent manifest/config mapping."""
+    if fabric_agent_config is None:
+        return None
+    runtime = fabric_agent_config.get("required_framework") or fabric_agent_config.get("runtime") or fabric_agent_config.get("framework")
+    return _normalize_runtime(str(runtime)) if runtime else None
+
+
+def _require_available(runtime: str) -> str:
+    """Return a runtime or raise install guidance."""
+    from agentic_fabric.core.decomposer import is_framework_available
+
+    if not is_framework_available(runtime):
+        raise RuntimeUnavailableError(runtime, install_command(runtime))
+    return runtime

agentic_fabric/base/__init__.py

@@ -0,0 +1,150 @@
+"""Base module - reusable agent archetypes and shared tool re-exports.
+
+Archetypes are base templates that packages can extend in their own
+``agents.yaml``. Use the ``extends`` field to inherit from an archetype:
+
+.. code:: yaml
+
+   my_engineer:
+     extends: senior_engineer
+     variables:
+       language: Python
+     backstory: |
+       {base}
+       Additional context specific to my package...
+
+The ``{base}`` placeholder in agent config is replaced with the
+archetype's value. ``{language}`` and other ``variables`` are interpolated
+into the resolved role/goal/backstory strings.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agentic_fabric.tools.file_tools import (
+    DirectoryListTool,
+    GameCodeReaderTool,
+    GameCodeWriterTool,
+)
+
+
+logger = logging.getLogger(__name__)
+
+_ARCHETYPES_PATH = Path(__file__).parent / "archetypes.yaml"
+
+
+def _load_archetypes() -> dict[str, dict[str, Any]]:
+    """Load built-in archetypes from the bundled YAML file."""
+    try:
+        data = yaml.safe_load(_ARCHETYPES_PATH.read_text(encoding="utf-8"))
+    except OSError as exc:
+        logger.warning("Could not load archetypes.yaml: %s", exc)
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return data.get("archetypes", {})
+
+
+def _interpolate(text: str, variables: dict[str, Any]) -> str:
+    """Interpolate ``{key}`` placeholders in *text* using *variables*."""
+    if not text:
+        return text
+    try:
+        return text.format(**variables)
+    except (KeyError, IndexError, ValueError):
+        return text
+
+
+def resolve_archetype(
+    agent_config: dict[str, Any],
+    *,
+    archetypes: dict[str, dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Resolve ``extends`` and ``variables`` in an agent config.
+
+    If the config has an ``extends`` key, the named archetype is loaded
+    and its role/goal/backstory are merged. ``{base}`` in the agent's
+    own field is replaced with the archetype's value. Other ``{variables}``
+    are interpolated into the final resolved strings.
+
+    Args:
+        agent_config: Raw agent config dict that may contain ``extends``
+            and ``variables``.
+        archetypes: Optional pre-loaded archetypes dict. If ``None``,
+            built-in archetypes are loaded from ``archetypes.yaml``.
+
+    Returns:
+        New config dict with ``extends`` and ``variables`` consumed
+        and all string fields interpolated.
+    """
+    extends = agent_config.get("extends")
+    if not extends:
+        return dict(agent_config)
+
+    if archetypes is None:
+        archetypes = _load_archetypes()
+
+    archetype = archetypes.get(extends)
+    if archetype is None:
+        logger.warning("Agent config extends unknown archetype '%s'", extends)
+        result = dict(agent_config)
+        result.pop("extends", None)
+        result.pop("variables", None)
+        return result
+
+    variables = agent_config.get("variables", {})
+    if not isinstance(variables, dict):
+        variables = {}
+
+    resolved: dict[str, Any] = dict(agent_config)
+    resolved.pop("extends", None)
+    resolved.pop("variables", None)
+
+    for field in ("role", "goal", "backstory"):
+        agent_value = agent_config.get(field, "")
+        archetype_value = archetype.get(field, "")
+        # {base} in the agent's value is replaced with the archetype value
+        merged = agent_value.replace("{base}", archetype_value) if agent_value else archetype_value
+        resolved[field] = _interpolate(merged, variables)
+
+    # Copy any fields from the archetype not overridden by the agent
+    for key, value in archetype.items():
+        if key not in resolved:
+            resolved[key] = value
+
+    return resolved
+
+
+def resolve_agent_archetypes(
+    agents_config: dict[str, dict[str, Any]],
+    *,
+    archetypes: dict[str, dict[str, Any]] | None = None,
+) -> dict[str, dict[str, Any]]:
+    """Resolve archetypes for every agent in a config dict.
+
+    Args:
+        agents_config: Dict mapping agent names to agent configs.
+        archetypes: Optional pre-loaded archetypes dict.
+
+    Returns:
+        New dict with archetypes resolved for each agent.
+    """
+    return {
+        name: resolve_archetype(config, archetypes=archetypes)
+        for name, config in agents_config.items()
+    }
+
+
+__all__ = [
+    "DirectoryListTool",
+    "GameCodeReaderTool",
+    "GameCodeWriterTool",
+    "resolve_agent_archetypes",
+    "resolve_archetype",
+]

agentic_fabric/base/archetypes.yaml

@@ -0,0 +1,75 @@
+# Reusable Agent Archetypes
+#
+# These are base templates that packages can extend in their own agents.yaml.
+# Use the 'extends' field to inherit from an archetype.
+#
+# Example usage in packages/mypackage/.fabric/fabric_agents/builder/agents.yaml:
+#   my_engineer:
+#     extends: senior_engineer
+#     variables:
+#       language: Python
+#     backstory: |
+#       {base}
+#       Additional context specific to my package...
+
+archetypes:
+  senior_engineer:
+    role: "Senior {language} Engineer"
+    goal: >
+      Write production-quality {language} code following best practices
+      and existing patterns in the codebase.
+    backstory: >
+      You are a senior developer with 10+ years of experience.
+      You always read existing code before writing new code.
+      You follow project conventions exactly.
+      You write clean, well-documented code with proper types.
+
+  qa_engineer:
+    role: "Quality Assurance Engineer"
+    goal: >
+      Review code for errors, security issues, type safety problems,
+      and deviations from project conventions.
+    backstory: >
+      You specialize in code review with an eye for:
+      - Type safety and proper interface usage
+      - Missing imports that would cause errors
+      - Inconsistent naming conventions
+      - Performance anti-patterns
+      - Security vulnerabilities
+
+  technical_lead:
+    role: "Technical Lead"
+    goal: >
+      Ensure all code is complete, correct, and properly integrated
+      with the existing architecture.
+    backstory: >
+      You are the technical lead with final approval authority.
+      You verify:
+      - Code fulfills the original requirement
+      - Architecture patterns are followed
+      - Code integrates with existing systems
+      - No regressions or breaking changes
+
+  architect:
+    role: "Software Architect"
+    goal: >
+      Design scalable, maintainable system architectures and
+      ensure code follows established patterns.
+    backstory: >
+      You are a software architect focused on:
+      - Clean architecture principles
+      - SOLID design patterns
+      - Separation of concerns
+      - Extensibility and maintainability
+
+  designer:
+    role: "System Designer"
+    goal: >
+      Create detailed designs and specifications for new features
+      that align with project goals.
+    backstory: >
+      You are a system designer who:
+      - Translates requirements into technical designs
+      - Considers edge cases and error handling
+      - Documents design decisions
+      - Balances complexity with maintainability