cemaf 0.1.0__py3-none-any.whl

cemaf/__init__.py

@@ -0,0 +1,34 @@
+"""
+CEMAF - Context Engineering Multi-Agent Framework
+
+A pluggable, modular framework for building AI agent systems with:
+- Tools: Atomic, stateless functions
+- Skills: Composable capabilities using tools
+- Agents: Autonomous entities with goals and memory
+- DeepAgent: Hierarchical orchestration with context isolation
+- Dynamic DAGs: Runtime workflow composition
+
+Author: Hikuri Bado Chinca (@drchinca)
+Email: chincadr@gmail.com
+"""
+
+__version__ = "0.1.0"
+
+from cemaf.core.enums import AgentStatus, MemoryScope, NodeType, RunStatus
+from cemaf.core.types import JSON, AgentID, NodeID, RunID, SkillID, ToolID
+
+__all__ = [
+    "__version__",
+    # Types
+    "JSON",
+    "AgentID",
+    "NodeID",
+    "RunID",
+    "SkillID",
+    "ToolID",
+    # Enums
+    "AgentStatus",
+    "MemoryScope",
+    "NodeType",
+    "RunStatus",
+]

cemaf/agents/__init__.py

@@ -0,0 +1,63 @@
+"""
+Agents module - Autonomous entities with goals and memory.
+
+Agents are the HIGHEST level of the execution hierarchy:
+- AUTONOMOUS: Make decisions about which skills to use
+- GOAL-ORIENTED: Work toward completing objectives
+- MEMORY-ENABLED: Maintain state across interactions
+- CONTEXT-AWARE: Have isolated context scope
+
+Agents USE Skills (which USE Tools).
+
+## Configuration
+
+Settings for this module are defined in AgentsSettings.
+
+Environment Variables:
+    CEMAF_AGENTS_MAX_ITERATIONS: Max agent iterations (default: 10)
+    CEMAF_AGENTS_MAX_SKILL_CALLS: Max skill calls per agent (default: 50)
+    CEMAF_AGENTS_TIMEOUT_SECONDS: Agent timeout in seconds (default: 300.0)
+    CEMAF_AGENTS_DEEP_AGENT_MAX_DEPTH: Max depth for DeepAgent (default: 5)
+    CEMAF_AGENTS_DEEP_AGENT_MAX_CHILDREN: Max children per node (default: 10)
+    CEMAF_AGENTS_DEEP_AGENT_MAX_TOTAL: Max total agents (default: 100)
+    CEMAF_AGENTS_DEEP_AGENT_TIMEOUT_SECONDS: DeepAgent timeout (default: 600.0)
+
+## Usage
+
+Protocol-based (Recommended):
+    >>> from cemaf.agents import Agent, AgentContext, AgentResult, AgentState
+    >>> from cemaf.core.types import AgentID
+    >>>
+    >>> class MyAgent:
+    ...     @property
+    ...     def id(self) -> AgentID:
+    ...         return AgentID("my_agent")
+    ...
+    ...     @property
+    ...     def description(self) -> str:
+    ...         return "My custom agent"
+    ...
+    ...     @property
+    ...     def skills(self) -> tuple:
+    ...         return ()
+    ...
+    ...     async def run(self, goal, context: AgentContext) -> AgentResult:
+    ...         return AgentResult.ok("result", AgentState())
+
+## Extension
+
+Agent implementations are discovered via protocols. No registration needed.
+Simply implement the Agent protocol and your agent is compatible with all
+CEMAF orchestration systems.
+
+See cemaf.agents.protocols.Agent for the protocol definition.
+"""
+
+from cemaf.agents.protocols import Agent, AgentContext, AgentResult, AgentState
+
+__all__ = [
+    "Agent",
+    "AgentState",
+    "AgentResult",
+    "AgentContext",
+]

cemaf/agents/base.py

@@ -0,0 +1,191 @@
+"""
+Agent base classes.
+
+An Agent is:
+- Autonomous entity with a goal
+- Uses skills to accomplish tasks
+- Maintains state/memory
+- Can make decisions
+
+## Best Practices
+
+### Using VectorStore and Memory Stores
+
+When skills or agents retrieve from vector stores or memory stores, they should:
+
+1. **Emit context patches** for retrieval results so downstream nodes can reuse them:
+
+    ```python
+    # In a skill or agent:
+    retrieved_docs = await vector_store.search(query, top_k=5)
+
+    # Patch retrieval results into context
+    context = context.set("retrieved_docs", retrieved_docs)
+    # Or use ContextPatch explicitly for better provenance tracking
+    ```
+
+2. **Store retrieval metadata** (query, timestamp, scores) for debugging:
+
+    ```python
+    metadata = {
+        "query": query,
+        "num_results": len(results),
+        "top_score": results[0].score if results else None,
+    }
+    ```
+
+3. **Use caching** for expensive retrieval operations (see below)
+
+### Resilience Patterns
+
+Use resilience decorators around expensive or flaky operations:
+
+```python
+from cemaf.resilience import retry, circuit_breaker
+
+class RetrievalSkill(Skill):
+    @retry(max_attempts=3, backoff_factor=1.5)
+    @circuit_breaker(failure_threshold=5, recovery_timeout=60)
+    async def search_vector_store(self, query: str) -> list[Document]:
+        # Expensive retrieval operation
+        return await self.vector_store.search(query)
+```
+
+### Caching Patterns
+
+Use caching decorators for expensive calls (LLM, retrieval):
+
+```python
+from cemaf.cache import cache_result
+
+class AnalysisAgent(Agent):
+    @cache_result(ttl=3600)  # Cache for 1 hour
+    async def analyze_with_llm(self, text: str) -> AnalysisResult:
+        # Expensive LLM call
+        return await self.llm.complete(...)
+
+    @cache_result(ttl=600, key_prefix="retrieval")
+    async def retrieve_context(self, query: str) -> list[Document]:
+        # Expensive retrieval
+        return await self.vector_store.search(query)
+```
+
+See examples/retrieval_dag_example.py for a complete working example.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, Field
+
+from cemaf.core.enums import AgentStatus
+from cemaf.core.types import JSON, AgentID
+from cemaf.skills.base import Skill, SkillResult
+
+GoalT = TypeVar("GoalT", bound=BaseModel)
+ResultT = TypeVar("ResultT")
+
+
+class AgentState(BaseModel):
+    """Mutable state during agent execution."""
+
+    model_config = {"frozen": True}
+
+    status: AgentStatus = AgentStatus.IDLE
+    iteration: int = 0
+    skill_calls: int = 0
+    messages: tuple[JSON, ...] = ()
+    working_memory: JSON = Field(default_factory=dict)
+
+    def next(self, **updates: Any) -> AgentState:
+        """Create new state with updates."""
+        data = self.model_dump()
+        data.update(updates)
+        return AgentState(**data)
+
+
+@dataclass(frozen=True)
+class AgentResult[ResultT]:
+    """Result of agent execution with state trace."""
+
+    success: bool
+    output: ResultT | None = None
+    error: str | None = None
+    final_state: AgentState | None = None
+    skill_results: tuple[SkillResult, ...] = ()
+    metadata: JSON = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Ensure trace collections remain immutable and replay-safe."""
+        object.__setattr__(self, "skill_results", tuple(self.skill_results))
+
+    @classmethod
+    def ok(cls, output: ResultT, state: AgentState) -> AgentResult[ResultT]:
+        return cls(success=True, output=output, final_state=state)
+
+    @classmethod
+    def fail(cls, error: str, state: AgentState | None = None) -> AgentResult[ResultT]:
+        return cls(success=False, error=error, final_state=state)
+
+
+class AgentContext(BaseModel):
+    """Isolated context for agent execution."""
+
+    model_config = {"frozen": True}
+
+    run_id: str
+    agent_id: str
+    parent_agent_id: str | None = None
+    depth: int = 0
+    global_memory: JSON = Field(default_factory=dict)
+    artifacts: JSON = Field(default_factory=dict)
+
+
+class Agent[GoalT: BaseModel, ResultT](ABC):
+    """
+    Abstract base class for agents.
+
+    Example:
+        class AnalystAgent(Agent[AnalysisGoal, AnalysisResult]):
+            def __init__(self, sql_skill: Skill):
+                self._sql = sql_skill
+
+            @property
+            def id(self) -> AgentID:
+                return AgentID("analyst")
+
+            @property
+            def skills(self) -> tuple[Skill, ...]:
+                return (self._sql,)
+
+            async def run(self, goal: AnalysisGoal, ctx: AgentContext) -> AgentResult:
+                state = AgentState()
+                result = await self._sql.execute(...)
+                if not result.success:
+                    return AgentResult.fail(result.error, state)
+                return AgentResult.ok(AnalysisResult(data=result.data), state)
+    """
+
+    @property
+    @abstractmethod
+    def id(self) -> AgentID:
+        """Unique identifier."""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """What this agent does."""
+        ...
+
+    @property
+    @abstractmethod
+    def skills(self) -> tuple[Skill[Any, Any], ...]:
+        """Skills available to this agent."""
+        ...
+
+    @abstractmethod
+    async def run(self, goal: GoalT, context: AgentContext) -> AgentResult[ResultT]:
+        """Execute the agent to accomplish a goal."""
+        ...

cemaf/agents/factories.py

@@ -0,0 +1,141 @@
+"""
+Factory functions for agent components.
+
+Provides convenient ways to create agent contexts and configurations
+with sensible defaults while maintaining dependency injection principles.
+
+Note:
+    Agents are protocol-based abstractions that users implement.
+    This module provides factory functions for agent contexts and configurations,
+    not for agent instances themselves.
+
+Extension Point:
+    This module is designed for extension. Add your custom agent
+    implementations and register them here if needed.
+"""
+
+import os
+
+from cemaf.agents.protocols import AgentContext
+from cemaf.config.protocols import Settings
+from cemaf.context.context import Context
+from cemaf.core.types import AgentID
+
+
+def create_agent_context(
+    agent_id: AgentID,
+    context: Context | None = None,
+    max_iterations: int = 10,
+    max_skill_calls: int = 50,
+    timeout_seconds: float = 300.0,
+) -> AgentContext:
+    """
+    Factory for AgentContext with sensible defaults.
+
+    Args:
+        agent_id: Unique agent identifier
+        context: Base context (creates new if None)
+        max_iterations: Maximum agent iterations
+        max_skill_calls: Maximum skill calls per agent
+        timeout_seconds: Agent execution timeout
+
+    Returns:
+        Configured AgentContext instance
+
+    Example:
+        # Basic agent context
+        from cemaf.core.types import AgentID
+        agent_ctx = create_agent_context(AgentID("my_agent"))
+
+        # With custom limits
+        agent_ctx = create_agent_context(
+            AgentID("my_agent"),
+            max_iterations=20,
+            timeout_seconds=600.0
+        )
+    """
+    base_context = context or Context.empty()
+
+    return AgentContext(
+        agent_id=agent_id,
+        context=base_context,
+        max_iterations=max_iterations,
+        max_skill_calls=max_skill_calls,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def create_agent_context_from_config(
+    agent_id: AgentID,
+    context: Context | None = None,
+    settings: Settings | None = None,
+) -> AgentContext:
+    """
+    Create AgentContext from environment configuration.
+
+    Reads from environment variables:
+    - CEMAF_AGENTS_MAX_ITERATIONS: Max iterations (default: 10)
+    - CEMAF_AGENTS_MAX_SKILL_CALLS: Max skill calls (default: 50)
+    - CEMAF_AGENTS_TIMEOUT_SECONDS: Timeout in seconds (default: 300.0)
+
+    Args:
+        agent_id: Unique agent identifier
+        context: Base context (creates new if None)
+
+    Returns:
+        Configured AgentContext instance
+
+    Example:
+        # From environment
+        from cemaf.core.types import AgentID
+        agent_ctx = create_agent_context_from_config(AgentID("my_agent"))
+    """
+    max_iterations = int(os.getenv("CEMAF_AGENTS_MAX_ITERATIONS", "10"))
+    max_skill_calls = int(os.getenv("CEMAF_AGENTS_MAX_SKILL_CALLS", "50"))
+    timeout_seconds = float(os.getenv("CEMAF_AGENTS_TIMEOUT_SECONDS", "300.0"))
+
+    return create_agent_context(
+        agent_id=agent_id,
+        context=context,
+        max_iterations=max_iterations,
+        max_skill_calls=max_skill_calls,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+# ============================================================================
+# EXTEND HERE: Bring Your Own Agent Implementations
+# ============================================================================
+# This is the extension point for custom agent implementations.
+#
+# To add your own agent type:
+# 1. Implement the Agent protocol (see cemaf.agents.protocols)
+# 2. Add a factory function below
+# 3. Optionally add a config-based factory
+#
+# Example (ReAct Agent):
+#   def create_react_agent(
+#       agent_id: AgentID,
+#       llm: LLMClient,
+#       skills: tuple[Skill, ...],
+#   ) -> Agent:
+#       from your_package import ReActAgent
+#       return ReActAgent(agent_id=agent_id, llm=llm, skills=skills)
+#
+#   def create_react_agent_from_config(
+#       agent_id: AgentID,
+#       skills: tuple[Skill, ...],
+#   , settings: Settings | None = None) -> Agent:
+#       from cemaf.llm.factories import create_llm_client_from_config
+#       llm = create_llm_client_from_config()
+#       return create_react_agent(agent_id, llm, skills)
+#
+# Example (Planning Agent):
+#   def create_planning_agent(
+#       agent_id: AgentID,
+#       llm: LLMClient,
+#       planner: Planner,
+#   ) -> Agent:
+#       from your_package import PlanningAgent
+#       return PlanningAgent(agent_id=agent_id, llm=llm, planner=planner)
+# ============================================================================

cemaf/agents/protocols.py

@@ -0,0 +1,220 @@
+"""
+Agent protocols - Abstract interfaces for autonomous agents.
+
+Supports:
+- Goal-oriented execution
+- Skill composition
+- State management
+- Iterative reasoning
+
+## Protocol-First Design
+
+This module provides structural typing via @runtime_checkable protocols.
+Any class that implements the required methods is automatically compatible.
+
+Extension Point:
+    Custom agent implementations should implement these protocols rather than
+    inheriting from ABC classes. This allows maximum flexibility and follows
+    CEMAF's dependency injection principles.
+
+Example:
+    >>> from cemaf.agents.protocols import Agent
+    >>> from cemaf.core.types import AgentID
+    >>>
+    >>> class MyCustomAgent:
+    ...     @property
+    ...     def id(self) -> AgentID:
+    ...         return AgentID("my_agent")
+    ...
+    ...     @property
+    ...     def description(self) -> str:
+    ...         return "My custom agent"
+    ...
+    ...     @property
+    ...     def skills(self) -> tuple[Any, ...]:
+    ...         return ()
+    ...
+    ...     async def run(self, goal: Any, context: AgentContext) -> AgentResult:
+    ...         return AgentResult.ok("result", AgentState())
+    >>>
+    >>> # No inheritance needed - structural compatibility!
+    >>> assert isinstance(MyCustomAgent(), Agent)
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+# Re-export data classes from base (these are not changed)
+from cemaf.agents.base import AgentContext, AgentResult, AgentState
+from cemaf.core.types import AgentID
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "AgentResult",
+    "AgentState",
+]
+
+
+@runtime_checkable
+class Agent[GoalT, ResultT](Protocol):
+    """
+    Protocol for agent implementations.
+
+    An Agent is an autonomous entity that:
+    - Has a unique identifier
+    - Has a clear purpose/description
+    - Composes skills to accomplish goals
+    - Maintains state during execution
+    - Returns structured results
+
+    This is a protocol, not an ABC. Any class with these methods is compatible.
+
+    Type Parameters:
+        GoalT: Type of goal this agent accepts (typically a Pydantic model)
+        ResultT: Type of result this agent produces
+
+    Extension Point:
+        Implement this protocol for custom agents:
+        - ReAct agents (reasoning + acting)
+        - Planning agents (goal decomposition)
+        - Conversational agents (dialogue management)
+        - Domain-specific agents (SQL, code analysis, etc.)
+
+    Example:
+        >>> class AnalystAgent:
+        ...     def __init__(self, sql_skill):
+        ...         self._sql_skill = sql_skill
+        ...
+        ...     @property
+        ...     def id(self) -> AgentID:
+        ...         return AgentID("analyst")
+        ...
+        ...     @property
+        ...     def description(self) -> str:
+        ...         return "Analyzes data using SQL queries"
+        ...
+        ...     @property
+        ...     def skills(self) -> tuple[Skill, ...]:
+        ...         return (self._sql_skill,)
+        ...
+        ...     async def run(self, goal: AnalysisGoal, ctx: AgentContext) -> AgentResult[AnalysisResult]:
+        ...         state = AgentState()
+        ...         result = await self._sql_skill.execute(goal.query, ctx)
+        ...         if not result.success:
+        ...             return AgentResult.fail(result.error, state)
+        ...         return AgentResult.ok(AnalysisResult(data=result.output), state)
+        >>>
+        >>> # Automatically compatible - no inheritance!
+        >>> agent = AnalystAgent(sql_skill)
+        >>> assert isinstance(agent, Agent)
+
+    Best Practices:
+        1. **Dependency Injection**: Accept all dependencies in __init__
+        2. **Immutable State**: Return new AgentState, never mutate
+        3. **Result Pattern**: Always return AgentResult[T], never raise
+        4. **Skill Composition**: Use skills for reusable capabilities
+        5. **Context Isolation**: Each agent has isolated AgentContext
+
+    See Also:
+        - cemaf.agents.base.Agent (deprecated ABC, use this protocol instead)
+        - cemaf.skills.protocols.Skill (skill protocol)
+        - cemaf.orchestration.deep_agent.DeepAgent (hierarchical agent orchestration)
+    """
+
+    @property
+    def id(self) -> AgentID:
+        """
+        Unique identifier for this agent.
+
+        Returns:
+            AgentID instance (typically AgentID("name"))
+
+        Example:
+            >>> @property
+            >>> def id(self) -> AgentID:
+            ...     return AgentID("my_agent")
+        """
+        ...
+
+    @property
+    def description(self) -> str:
+        """
+        Human-readable description of what this agent does.
+
+        Returns:
+            Clear, concise description of agent's purpose
+
+        Example:
+            >>> @property
+            >>> def description(self) -> str:
+            ...     return "Analyzes data and generates reports"
+        """
+        ...
+
+    @property
+    def skills(self) -> tuple[Any, ...]:
+        """
+        Skills available to this agent.
+
+        Skills are composable capabilities that agents use to accomplish goals.
+        This tuple defines which skills this agent has access to.
+
+        Returns:
+            Tuple of Skill instances (empty tuple if no skills)
+
+        Example:
+            >>> @property
+            >>> def skills(self) -> tuple[Skill, ...]:
+            ...     return (self._sql_skill, self._analysis_skill)
+        """
+        ...
+
+    async def run(self, goal: GoalT, context: AgentContext) -> AgentResult[ResultT]:
+        """
+        Execute the agent to accomplish a goal.
+
+        This is the main entry point for agent execution. The agent should:
+        1. Validate the goal
+        2. Plan approach (if needed)
+        3. Execute skills to accomplish goal
+        4. Track state throughout execution
+        5. Return structured result
+
+        Args:
+            goal: Goal to accomplish (typically a Pydantic model)
+            context: Execution context with run metadata, parent info, memory
+
+        Returns:
+            AgentResult containing:
+            - success: Whether goal was accomplished
+            - output: The result data (if successful)
+            - error: Error message (if failed)
+            - final_state: Final agent state
+            - skill_results: Trace of skill executions
+            - metadata: Additional execution metadata
+
+        Example:
+            >>> async def run(self, goal: AnalysisGoal, context: AgentContext) -> AgentResult[AnalysisResult]:
+            ...     state = AgentState()
+            ...
+            ...     # Execute skills
+            ...     result = await self._sql_skill.execute(goal.query, context)
+            ...     state = state.next(skill_calls=1)
+            ...
+            ...     if not result.success:
+            ...         return AgentResult.fail(result.error, state)
+            ...
+            ...     # Process results
+            ...     analysis = self._analyze_data(result.output)
+            ...     state = state.next(status=AgentStatus.COMPLETED)
+            ...
+            ...     return AgentResult.ok(AnalysisResult(data=analysis), state)
+
+        Best Practices:
+            - Always return AgentResult, never raise exceptions
+            - Track iterations and skill calls in state
+            - Include metadata for debugging/observability
+            - Use context patches to share data with downstream nodes
+            - Check cancellation tokens if long-running
+        """
+        ...

cemaf/blueprint/__init__.py

@@ -0,0 +1,31 @@
+"""
+Blueprint module for defining scene blueprints.
+
+Blueprints describe the structure and requirements for content generation scenes.
+"""
+
+from cemaf.blueprint.builder import BlueprintBuilder
+from cemaf.blueprint.mock import MockBlueprintRegistry, create_mock_blueprint
+from cemaf.blueprint.rules import BlueprintContentRule, BlueprintSchemaRule
+from cemaf.blueprint.schema import (
+    Blueprint,
+    Participant,
+    SceneGoal,
+    StyleGuide,
+)
+
+__all__ = [
+    # Schema models
+    "Blueprint",
+    "Participant",
+    "SceneGoal",
+    "StyleGuide",
+    # Builder
+    "BlueprintBuilder",
+    # Validation rules
+    "BlueprintContentRule",
+    "BlueprintSchemaRule",
+    # Mocks for testing
+    "MockBlueprintRegistry",
+    "create_mock_blueprint",
+]