apex-core 0.9.0__py3-none-any.whl

apex_core/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""
+APEX Platform - Multi-Cloud Infrastructure Orchestration Library
+
+A provider-agnostic platform for orchestrating cloud infrastructure operations
+with state management, execution planning, and conditional workflows.
+
+Key Features:
+- Multi-provider support (AWS, Azure, GCP, Kubernetes)
+- State-aware execution with variable interpolation
+- Execution planning with validation and rollback
+- Dynamic class loading from YAML configuration
+- MCP (Model Context Protocol) integration
+"""
+
+from .core.platform import APEXPlatform
+
+__version__ = "1.0.0"
+__author__ = "APEX Platform Team"
+
+__all__ = [
+    "APEXPlatform"
+]

apex_core/agents/__init__.py

@@ -0,0 +1,13 @@
+"""
+APEX Platform Agents
+
+Config-driven, factory-based multi-domain agent system built on LangGraph Swarm.
+
+Architecture:
+  SwarmOrchestrator — routes queries to domain agents, manages multi-turn state
+  AgentFactory      — creates domain agents from YAML config definitions
+  AgentConfigLoader — discovers and validates agent YAML configs
+  DomainAgent       — wraps a compiled LangGraph ReAct agent for one domain
+  tool_wrapper      — builds middleware-compliant LangChain StructuredTools
+  InteractionLogger — logs routing decisions + tool calls to interactions.jsonl
+"""

apex_core/agents/agent_config.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+Agent configuration models and config context detection.
+
+Contains:
+  ConfigContext      — project vs global context detection
+  AgentDomainConfig  — Pydantic model for agent YAML configs
+  ModelConfig        — nested LLM model configuration
+  QueryExample       — training/test example in agent config
+  AgentConfigLoader  — discovers and validates agent YAML configs
+  AgentConfigError   — raised on config validation failures
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Config Context
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ConfigContext:
+    """Determines which configs/skills/tools are available based on context.
+
+    Project context: .apex/settings.yaml exists in cwd or a parent directory.
+    Global context:  no project config found; uses ~/.apex/ defaults.
+    """
+
+    mode: str                          # "project" | "global"
+    project_dir: Optional[Path]        # Project root (where .apex/ lives)
+    global_dir: Path                   # Always ~/.apex/
+    allowed_skills: Optional[List[str]]  = field(default=None)  # None = all
+    allowed_agents: Optional[List[str]]  = field(default=None)  # None = all
+    skills_repo: Optional[str]           = field(default=None)
+    projects_repo: Optional[str]         = field(default=None)
+
+    @classmethod
+    def detect(cls, cwd: Path = None) -> "ConfigContext":
+        """Auto-detect context by walking up from cwd looking for .apex/settings.yaml.
+
+        Args:
+            cwd: Starting directory. Defaults to Path.cwd().
+
+        Returns:
+            ConfigContext with mode="project" if found, else mode="global".
+        """
+        cwd = cwd or Path.cwd()
+        global_dir = Path.home() / ".apex"
+
+        # Walk up the directory tree looking for .apex/settings.yaml
+        current = cwd
+        while True:
+            candidate = current / ".apex" / "settings.yaml"
+            if candidate.exists():
+                # Found project context — load project-level overrides
+                allowed_skills = None
+                allowed_agents = None
+                skills_repo = None
+                projects_repo = None
+
+                try:
+                    with open(candidate) as f:
+                        data = yaml.safe_load(f) or {}
+                    agents_cfg = data.get("agents", {})
+                    skills_cfg = data.get("skills", {})
+                    allowed_skills = agents_cfg.get("allowed_skills") or skills_cfg.get("allowed_skills")
+                    allowed_agents = agents_cfg.get("allowed_agents")
+                    skills_repo = skills_cfg.get("skills_repo")
+                    projects_repo = skills_cfg.get("projects_repo")
+                except Exception as e:
+                    logger.warning("Failed to read project settings at %s: %s", candidate, e)
+
+                return cls(
+                    mode="project",
+                    project_dir=current,
+                    global_dir=global_dir,
+                    allowed_skills=allowed_skills,
+                    allowed_agents=allowed_agents,
+                    skills_repo=skills_repo,
+                    projects_repo=projects_repo,
+                )
+
+            parent = current.parent
+            if parent == current:
+                break  # Reached filesystem root
+            current = parent
+
+        # No project config found — global context
+        return cls(
+            mode="global",
+            project_dir=None,
+            global_dir=global_dir,
+        )
+
+    @property
+    def settings_path(self) -> Path:
+        """Return the active settings.yaml path."""
+        if self.project_dir:
+            return self.project_dir / ".apex" / "settings.yaml"
+        return self.global_dir / "settings.yaml"
+
+    @property
+    def skills_dir(self) -> Path:
+        """Return ~/.apex/skills/ directory."""
+        return self.global_dir / "skills"
+
+    @property
+    def conversations_db(self) -> Path:
+        """Return path to shared conversations database."""
+        return self.global_dir / "conversations.db"
+
+
+# ---------------------------------------------------------------------------
+# Pydantic models for agent YAML configs
+# ---------------------------------------------------------------------------
+
+
+class QueryExample(BaseModel):
+    """A single training/test example embedded in the agent config."""
+
+    query: str = Field(description="Natural language user query")
+    tool: str = Field(description="Expected tool name (e.g., 'create_vpc')")
+    server: str = Field(description="Expected server name (e.g., 'aws_vpc')")
+    parameters: Dict[str, Any] = Field(default_factory=dict, description="Expected tool parameters")
+
+
+class AgentDomainConfig(BaseModel):
+    """Configuration for a domain agent, loaded from YAML.
+
+    One YAML file per domain in config/agents/*.yaml.
+    """
+
+    name: str = Field(description="Unique domain identifier (e.g., 'infrastructure')")
+    description: str = Field(description="Domain description — used for FAISS domain search")
+    skill: Optional[str] = Field(default=None, description="SKILL.md name reference")
+    memory_mode: str = Field(default="persistent", description="'persistent' or 'stateless'")
+    resource_servers: List[str] = Field(description="ResourceServer names (e.g., ['aws_vpc', 'aws_subnet'])")
+    handoff_targets: List[str] = Field(default_factory=list, description="Sibling domain names for routing")
+    routing_keywords: List[str] = Field(default_factory=list, description="Keywords for fast-path routing")
+    system_prompt: Optional[str] = Field(default=None, description="Custom system prompt (overrides skill)")
+    examples: List[QueryExample] = Field(default_factory=list, description="Baseline training/test examples")
+
+    @field_validator("memory_mode")
+    @classmethod
+    def validate_memory_mode(cls, v: str) -> str:
+        allowed = {"persistent", "stateless"}
+        if v not in allowed:
+            raise ValueError(f"memory_mode must be one of {allowed}, got '{v}'")
+        return v
+
+    @field_validator("resource_servers")
+    @classmethod
+    def validate_resource_servers_not_empty(cls, v: List[str]) -> List[str]:
+        if not v:
+            raise ValueError("resource_servers must contain at least one server name")
+        return v
+
+
+# ---------------------------------------------------------------------------
+# Config loading error
+# ---------------------------------------------------------------------------
+
+
+class AgentConfigError(Exception):
+    """Raised when agent config is invalid or cannot be loaded."""
+
+
+# ---------------------------------------------------------------------------
+# AgentConfigLoader
+# ---------------------------------------------------------------------------
+
+
+class AgentConfigLoader:
+    """Discovers and validates agent domain configs from YAML files.
+
+    Loads all YAML files from config_dir matching *.yaml and parses them
+    into AgentDomainConfig instances.
+    """
+
+    def __init__(self, config_dir: Path = None):
+        """
+        Args:
+            config_dir: Path to agents config directory.
+                        Default: auto-discovers config/agents/ relative to this file.
+        """
+        if config_dir is None:
+            # Auto-discover: walk up from this file to find config/agents/
+            pkg_root = Path(__file__).parent.parent.parent.parent  # src/../.. = repo root
+            config_dir = pkg_root / "config" / "agents"
+
+        self.config_dir = config_dir
+
+    def load_all(self) -> Dict[str, AgentDomainConfig]:
+        """Load all agent configs from config_dir.
+
+        Returns:
+            Dict mapping domain name to validated AgentDomainConfig.
+
+        Raises:
+            AgentConfigError: If any config file is invalid.
+        """
+        if not self.config_dir.exists():
+            logger.warning("Agent config directory not found: %s", self.config_dir)
+            return {}
+
+        configs: Dict[str, AgentDomainConfig] = {}
+
+        for yaml_file in sorted(self.config_dir.glob("*.yaml")):
+            try:
+                config = self._load_file(yaml_file)
+                configs[config.name] = config
+                logger.debug("Loaded agent config: %s from %s", config.name, yaml_file.name)
+            except Exception as e:
+                raise AgentConfigError(
+                    f"Failed to load agent config from {yaml_file.name}: {e}"
+                ) from e
+
+        logger.info("Loaded %d agent configs from %s", len(configs), self.config_dir)
+        return configs
+
+    def load_one(self, name: str) -> AgentDomainConfig:
+        """Load a single agent config by domain name.
+
+        Args:
+            name: Domain name (matches the 'name' field in YAML, not filename).
+
+        Raises:
+            AgentConfigError: If the config is not found or invalid.
+        """
+        yaml_file = self.config_dir / f"{name}.yaml"
+        if not yaml_file.exists():
+            raise AgentConfigError(f"Agent config not found: {yaml_file}")
+        return self._load_file(yaml_file)
+
+    def _load_file(self, path: Path) -> AgentDomainConfig:
+        """Parse a single YAML file into AgentDomainConfig."""
+        with open(path) as f:
+            data = yaml.safe_load(f) or {}
+        try:
+            return AgentDomainConfig(**data)
+        except Exception as e:
+            raise AgentConfigError(f"Invalid config in {path.name}: {e}") from e
+
+    def validate(
+        self,
+        config: AgentDomainConfig,
+        all_configs: Dict[str, AgentDomainConfig],
+        known_servers: Optional[List[str]] = None,
+    ) -> List[str]:
+        """Validate config against known servers and sibling configs.
+
+        Args:
+            config: Config to validate.
+            all_configs: All other configs (for handoff target validation).
+            known_servers: List of known ResourceServer names from platform.
+                           If None, server validation is skipped.
+
+        Returns:
+            List of validation error messages (empty if valid).
+        """
+        errors: List[str] = []
+
+        # Validate resource_servers against known platform servers
+        if known_servers is not None:
+            for server in config.resource_servers:
+                if server not in known_servers:
+                    errors.append(
+                        f"resource_server '{server}' not found in platform. "
+                        f"Available: {known_servers}"
+                    )
+
+        # Validate handoff_targets reference real agent configs
+        for target in config.handoff_targets:
+            if target == config.name:
+                errors.append(f"handoff_target '{target}' cannot reference itself")
+            elif target not in all_configs:
+                errors.append(
+                    f"handoff_target '{target}' not found in loaded agent configs. "
+                    f"Available: {list(all_configs.keys())}"
+                )
+
+        return errors

apex_core/agents/agent_factory.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""
+AgentFactory — creates DomainAgent instances from AgentDomainConfig.
+
+One factory per platform session. Receives the platform instance and a single
+shared LLM (from llm_factory.resolve_llm). All domain agents share the same
+LLM — model choice is a user-level concern, not per-agent.
+
+Persistent agents share one AsyncSqliteSaver at ~/.apex/conversations.db,
+with thread isolation via domain-prefixed thread IDs.
+Stateless agents get no checkpointer — fresh context each session.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, Optional
+
+from langgraph.prebuilt import create_react_agent
+
+from apex_core.agents.agent_config import AgentDomainConfig
+from apex_core.agents.domain_agent import DomainAgent
+from apex_core.agents.tool_wrapper import build_domain_tools
+
+if TYPE_CHECKING:
+    from langchain_core.language_models import BaseChatModel
+    from apex_core.core.platform import APEXPlatform
+
+logger = logging.getLogger(__name__)
+
+_GENERIC_SYSTEM_PROMPT = """You are an APEX Platform domain agent for the {domain} domain.
+
+You help users manage {description}.
+
+Available tools cover: {servers}.
+
+Guidelines:
+- Always confirm intent before executing destructive operations
+- Default to dry-run (plan) mode unless user explicitly requests apply/execute
+- Be concise and precise — infrastructure tasks need accuracy
+- If a request is outside your domain, say so clearly
+"""
+
+
+class AgentFactory:
+    """Creates DomainAgent instances from YAML config definitions.
+
+    Args:
+        platform:     Initialized APEXPlatform with resource servers loaded.
+        llm:          Shared LangChain chat model (from llm_factory.resolve_llm()).
+        checkpointer: Optional pre-initialized AsyncSqliteSaver.
+                      If None, created lazily at ~/.apex/conversations.db
+                      when the first persistent agent is requested.
+    """
+
+    def __init__(
+        self,
+        platform: "APEXPlatform",
+        llm: "BaseChatModel",
+        checkpointer=None,
+    ):
+        self.platform = platform
+        self.llm = llm
+        self._checkpointer = checkpointer  # shared, lazily initialized
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def create_agent(self, config: AgentDomainConfig) -> DomainAgent:
+        """Create a single domain agent from config.
+
+        Steps:
+        1. Build middleware-compliant tool wrappers for all resource servers
+        2. Load SKILL.md content (if configured)
+        3. Build system prompt
+        4. Create LangGraph ReAct agent with checkpointer
+        5. Return DomainAgent wrapper
+
+        Raises:
+            AgentConfigError: If required resource servers are missing.
+        """
+        # 1. Build tools — validates server availability
+        tools = build_domain_tools(config, self.platform)
+        if not tools:
+            logger.warning(
+                "Agent '%s' has no tools — resource servers %s may not be loaded",
+                config.name,
+                config.resource_servers,
+            )
+
+        # 2. Load skill content
+        skill_content = self._load_skill_content(config.skill)
+
+        # 3. Build system prompt
+        system_prompt = self._build_system_prompt(config, skill_content)
+
+        # 4. Get checkpointer (shared for persistent, None for stateless)
+        checkpointer = await self._get_checkpointer(config)
+
+        # 5. Create LangGraph ReAct agent
+        graph = create_react_agent(
+            model=self.llm,
+            tools=tools,
+            state_modifier=system_prompt,
+            checkpointer=checkpointer,
+        )
+
+        logger.info(
+            "Created domain agent '%s': %d tools, memory=%s, skill=%s",
+            config.name,
+            len(tools),
+            config.memory_mode,
+            config.skill or "none",
+        )
+
+        return DomainAgent(
+            config=config,
+            compiled_agent=graph,
+            tools=tools,
+            skill_prompt=skill_content or system_prompt,
+            active=True,
+            checkpointer=checkpointer,
+        )
+
+    async def create_all(
+        self, configs: Dict[str, AgentDomainConfig]
+    ) -> Dict[str, DomainAgent]:
+        """Create all domain agents from configs.
+
+        Persistent agents are early-loaded at startup.
+        Stateless agents are created but marked inactive — they'll be
+        re-created per session when needed (lazy loading).
+
+        Returns:
+            Dict mapping domain name → DomainAgent.
+        """
+        agents: Dict[str, DomainAgent] = {}
+
+        for name, config in configs.items():
+            try:
+                agent = await self.create_agent(config)
+                agents[name] = agent
+                logger.info("Loaded agent: %s (%s)", name, config.memory_mode)
+            except Exception as e:
+                logger.error("Failed to create agent '%s': %s", name, e)
+                # Continue loading other agents — partial startup is better than full failure
+
+        logger.info("AgentFactory: loaded %d/%d agents", len(agents), len(configs))
+        return agents
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_system_prompt(
+        self, config: AgentDomainConfig, skill_content: Optional[str]
+    ) -> str:
+        """Build the system prompt for a domain agent.
+
+        Priority:
+        1. config.system_prompt (explicit YAML override)
+        2. SKILL.md content (if skill configured and file exists)
+        3. Generic domain prompt template
+        """
+        if config.system_prompt:
+            return config.system_prompt
+
+        if skill_content:
+            return (
+                f"You are an APEX Platform domain agent for the {config.name} domain.\n\n"
+                f"Domain expertise (from SKILL.md):\n{skill_content}\n\n"
+                f"Available resource servers: {', '.join(config.resource_servers)}"
+            )
+
+        return _GENERIC_SYSTEM_PROMPT.format(
+            domain=config.name,
+            description=config.description,
+            servers=", ".join(config.resource_servers),
+        )
+
+    def _load_skill_content(self, skill_name: Optional[str]) -> Optional[str]:
+        """Load SKILL.md content from ~/.apex/skills/{skill_name}/SKILL.md.
+
+        Returns None if skill is not configured or file is missing.
+        Logs a warning if configured but missing (user should install it).
+        """
+        if not skill_name:
+            return None
+
+        skill_path = Path.home() / ".apex" / "skills" / skill_name / "SKILL.md"
+        if skill_path.exists():
+            try:
+                content = skill_path.read_text(encoding="utf-8")
+                logger.info("Loaded SKILL.md for '%s' from %s", skill_name, skill_path)
+                return content
+            except Exception as e:
+                logger.warning("Failed to read SKILL.md at %s: %s", skill_path, e)
+                return None
+
+        logger.warning(
+            "SKILL.md not found for skill '%s' at %s. "
+            "Install with: apex skills install %s",
+            skill_name,
+            skill_path,
+            skill_name,
+        )
+        return None
+
+    async def _get_checkpointer(self, config: AgentDomainConfig):
+        """Return the shared checkpointer for persistent agents, None for stateless.
+
+        All persistent agents share one AsyncSqliteSaver at ~/.apex/conversations.db.
+        Conversation isolation is via thread_id = "{domain}_{session_id}".
+        """
+        if config.memory_mode != "persistent":
+            return None
+
+        if self._checkpointer is None:
+            self._checkpointer = await self._init_checkpointer()
+
+        return self._checkpointer
+
+    async def _init_checkpointer(self):
+        """Initialize shared AsyncSqliteSaver at ~/.apex/conversations.db."""
+        try:
+            from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+
+            db_path = Path.home() / ".apex" / "conversations.db"
+            db_path.parent.mkdir(parents=True, exist_ok=True)
+
+            checkpointer = AsyncSqliteSaver.from_conn_string(str(db_path))
+            logger.info("Initialized shared checkpointer at %s", db_path)
+            return checkpointer
+
+        except Exception as e:
+            logger.error("Failed to initialize checkpointer: %s", e)
+            logger.warning("Persistent agents will run without memory this session")
+            return None

apex_core/agents/domain_agent.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+DomainAgent — wraps a compiled LangGraph ReAct agent for a single domain.
+
+Each domain agent:
+- Owns a scoped set of tools (only its resource servers' tools)
+- Has persistent or stateless memory (via SqliteSaver checkpointer)
+- Uses domain-prefixed thread IDs for conversation isolation:
+    thread_id = "{domain}_{session_id}"
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from langchain_core.messages import HumanMessage
+
+if TYPE_CHECKING:
+    from langchain_core.tools import StructuredTool
+    from langgraph.graph.state import CompiledStateGraph
+
+    from apex_core.agents.agent_config import AgentDomainConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DomainAgent:
+    """Runtime wrapper for a compiled LangGraph ReAct agent serving one domain.
+
+    Created by AgentFactory. Not persisted — rebuilt from config at startup.
+    """
+
+    config: "AgentDomainConfig"
+    compiled_agent: "CompiledStateGraph"
+    tools: List["StructuredTool"]
+    skill_prompt: str
+    active: bool = True
+    checkpointer: Optional[Any] = field(default=None, repr=False)
+
+    @property
+    def name(self) -> str:
+        return self.config.name
+
+    @property
+    def description(self) -> str:
+        return self.config.description
+
+    @property
+    def memory_mode(self) -> str:
+        return self.config.memory_mode
+
+    @property
+    def is_persistent(self) -> bool:
+        return self.config.memory_mode == "persistent"
+
+    def thread_id(self, session_id: str) -> str:
+        """Construct domain-scoped thread ID for checkpoint isolation.
+
+        All conversations with this domain agent under the same session
+        share one checkpoint thread, keeping conversation context across turns.
+        """
+        return f"{self.name}_{session_id}"
+
+    async def invoke(self, user_input: str, session_id: str) -> str:
+        """Process a single user message and return the agent's response.
+
+        Args:
+            user_input:  Natural language query from the user.
+            session_id:  Session identifier for multi-turn memory.
+
+        Returns:
+            Agent response as a plain string.
+        """
+        config = {"configurable": {"thread_id": self.thread_id(session_id)}}
+
+        try:
+            result = await self.compiled_agent.ainvoke(
+                {"messages": [HumanMessage(content=user_input)]},
+                config=config,
+            )
+            # Extract last AI message content
+            messages = result.get("messages", [])
+            if messages:
+                last = messages[-1]
+                content = last.content if hasattr(last, "content") else str(last)
+                return content if isinstance(content, str) else str(content)
+            return "No response from agent."
+
+        except Exception as e:
+            logger.error("DomainAgent '%s' invocation failed: %s", self.name, e)
+            return f"Error: {e}"
+
+    def get_info(self) -> Dict[str, Any]:
+        """Return agent metadata for display / info commands."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "memory_mode": self.memory_mode,
+            "resource_servers": self.config.resource_servers,
+            "tool_count": len(self.tools),
+            "tool_names": [t.name for t in self.tools],
+            "routing_keywords": self.config.routing_keywords,
+            "handoff_targets": self.config.handoff_targets,
+            "skill": self.config.skill,
+            "active": self.active,
+        }