ouroboros-ai 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ouroboros/__init__.py

@@ -13,7 +13,7 @@ Example:
     from ouroboros.bigbang import InterviewEngine
 """
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = ["__version__", "main"]
 

ouroboros/bigbang/__init__.py

@@ -14,6 +14,11 @@ from ouroboros.bigbang.ambiguity import (
     is_ready_for_seed,
 )
 from ouroboros.bigbang.interview import InterviewEngine, InterviewState
+from ouroboros.bigbang.ontology import (
+    InterviewOntologyAnalyzer,
+    OntologicalQuestionDecision,
+    default_interview_ontology_analyzer,
+)
 from ouroboros.bigbang.seed_generator import (
     SeedGenerator,
     load_seed,
@@ -32,6 +37,10 @@ __all__ = [
     # Interview
     "InterviewEngine",
     "InterviewState",
+    # Ontology (for Interview)
+    "InterviewOntologyAnalyzer",
+    "OntologicalQuestionDecision",
+    "default_interview_ontology_analyzer",
     # Seed Generation
     "SeedGenerator",
     "load_seed",

ouroboros/bigbang/ontology.py

@@ -0,0 +1,180 @@
+"""Ontological questioning integration for Interview Phase.
+
+This module provides the bridge between the core ontological framework
+and the Interview engine. It determines WHEN and WHICH ontological
+questions should be asked during the interview process.
+
+The Two Ancient Methods:
+1. Socratic Questioning (existing) - "Why?", "What if?"
+   → Reveals hidden assumptions through iterative questioning
+
+2. Ontological Analysis (this module) - "What IS this?", "Root cause or symptom?"
+   → Finds root problems, ensures we're solving the right thing
+
+These methods are interleaved: Socratic questions every round,
+ontological questions periodically to probe deeper.
+"""
+
+from dataclasses import dataclass
+
+from ouroboros.core.ontology_questions import (
+    ONTOLOGICAL_QUESTIONS,
+    OntologicalQuestionType,
+    build_ontological_prompt,
+)
+
+# Question schedule: which ontological question type to use at each milestone
+# Pattern: ESSENCE → ROOT_CAUSE → PREREQUISITES → HIDDEN_ASSUMPTIONS
+_QUESTION_SCHEDULE: tuple[OntologicalQuestionType, ...] = (
+    OntologicalQuestionType.ESSENCE,  # Round 3: What IS this?
+    OntologicalQuestionType.ROOT_CAUSE,  # Round 6: Root cause or symptom?
+    OntologicalQuestionType.PREREQUISITES,  # Round 9: What must exist first?
+    OntologicalQuestionType.HIDDEN_ASSUMPTIONS,  # Round 12+: What are we assuming?
+)
+
+
+@dataclass(frozen=True, slots=True)
+class OntologicalQuestionDecision:
+    """Decision about whether to ask an ontological question.
+
+    Attributes:
+        should_ask: Whether an ontological question should be asked this round.
+        question_type: The type of question to ask (if should_ask is True).
+        system_prompt_addition: Text to add to system prompt (if should_ask).
+    """
+
+    should_ask: bool
+    question_type: OntologicalQuestionType | None = None
+    system_prompt_addition: str = ""
+
+
+class InterviewOntologyAnalyzer:
+    """Analyzer that decides when to inject ontological questions.
+
+    Ontological questions are interspersed with Socratic questioning
+    to periodically probe the fundamental nature of the problem.
+
+    Schedule:
+    - Round 1-2: Pure Socratic (building basic context)
+    - Round 3: ESSENCE - "What IS this, really?"
+    - Round 4-5: Pure Socratic
+    - Round 6: ROOT_CAUSE - "Is this root cause or symptom?"
+    - Round 7-8: Pure Socratic
+    - Round 9: PREREQUISITES - "What must exist first?"
+    - Round 10-11: Pure Socratic
+    - Round 12+: HIDDEN_ASSUMPTIONS (every 3rd round after)
+    """
+
+    def __init__(self, start_round: int = 3, frequency: int = 3) -> None:
+        """Initialize the analyzer.
+
+        Args:
+            start_round: First round to start ontological questioning.
+            frequency: Ask ontological questions every N rounds.
+        """
+        self._start_round = start_round
+        self._frequency = frequency
+
+    def should_ask_ontological_question(self, round_number: int) -> bool:
+        """Determine if this round should include an ontological question.
+
+        Args:
+            round_number: Current interview round (1-based).
+
+        Returns:
+            True if ontological question should be asked.
+        """
+        if round_number < self._start_round:
+            return False
+        return (round_number - self._start_round) % self._frequency == 0
+
+    def select_question_type(
+        self,
+        round_number: int,
+    ) -> OntologicalQuestionType:
+        """Select which ontological question type to ask.
+
+        Uses a rotating schedule through the four question types.
+
+        Args:
+            round_number: Current interview round (1-based).
+
+        Returns:
+            The question type to use for this round.
+        """
+        if round_number < self._start_round:
+            # Default to ESSENCE for early rounds (shouldn't happen normally)
+            return OntologicalQuestionType.ESSENCE
+
+        # Calculate position in schedule
+        position = (round_number - self._start_round) // self._frequency
+        schedule_index = position % len(_QUESTION_SCHEDULE)
+        return _QUESTION_SCHEDULE[schedule_index]
+
+    def get_decision(self, round_number: int) -> OntologicalQuestionDecision:
+        """Get the complete decision for a round.
+
+        Args:
+            round_number: Current interview round (1-based).
+
+        Returns:
+            Decision with all necessary information.
+        """
+        should_ask = self.should_ask_ontological_question(round_number)
+
+        if not should_ask:
+            return OntologicalQuestionDecision(should_ask=False)
+
+        question_type = self.select_question_type(round_number)
+        prompt_addition = build_ontological_prompt(question_type)
+
+        return OntologicalQuestionDecision(
+            should_ask=True,
+            question_type=question_type,
+            system_prompt_addition=prompt_addition,
+        )
+
+    def build_ontological_system_prompt(
+        self,
+        round_number: int,
+        base_prompt: str,
+    ) -> str:
+        """Build system prompt with optional ontological addition.
+
+        If this round requires an ontological question, it's appended
+        to the base prompt. Otherwise, the base prompt is returned as-is.
+
+        Args:
+            round_number: Current interview round (1-based).
+            base_prompt: The base Socratic system prompt.
+
+        Returns:
+            Enhanced prompt with ontological guidance if applicable.
+        """
+        decision = self.get_decision(round_number)
+
+        if not decision.should_ask or decision.question_type is None:
+            return base_prompt
+
+        # Add ontological context
+        question = ONTOLOGICAL_QUESTIONS[decision.question_type]
+        return f"""{base_prompt}
+
+---
+ONTOLOGICAL FOCUS FOR THIS ROUND:
+{decision.system_prompt_addition}
+Your question this round should probe: {question.question}
+Purpose: {question.purpose}
+Consider: {question.follow_up}
+---"""
+
+
+# Default singleton for convenience
+default_interview_ontology_analyzer = InterviewOntologyAnalyzer()
+
+
+__all__ = [
+    "InterviewOntologyAnalyzer",
+    "OntologicalQuestionDecision",
+    "default_interview_ontology_analyzer",
+]

ouroboros/cli/commands/__init__.py

@@ -1,7 +1,9 @@
 """CLI command implementations for Ouroboros.
 
 This module contains the command group implementations:
+- init: Start interactive interview
 - run: Execute workflows
 - config: Manage configuration
 - status: Check system status
+- mcp: MCP server management
 """

ouroboros/cli/commands/mcp.py

@@ -0,0 +1,161 @@
+"""MCP command group for Ouroboros.
+
+Start and manage the MCP (Model Context Protocol) server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from ouroboros.cli.formatters.panels import print_error, print_info, print_success
+
+app = typer.Typer(
+    name="mcp",
+    help="MCP (Model Context Protocol) server commands.",
+    no_args_is_help=True,
+)
+
+
+async def _run_mcp_server(
+    host: str,
+    port: int,
+    transport: str,
+) -> None:
+    """Run the MCP server.
+
+    Args:
+        host: Host to bind to.
+        port: Port to bind to.
+        transport: Transport type (stdio or sse).
+    """
+    from ouroboros.mcp.server.adapter import create_ouroboros_server
+    from ouroboros.mcp.tools.definitions import OUROBOROS_TOOLS
+
+    # Create server
+    server = create_ouroboros_server(
+        name="ouroboros-mcp",
+        version="1.0.0",
+    )
+
+    # Register tools
+    for tool in OUROBOROS_TOOLS:
+        server.register_tool(tool)
+
+    print_success(f"MCP Server starting on {transport}...")
+    print_info(f"Registered {len(OUROBOROS_TOOLS)} tools")
+
+    if transport == "stdio":
+        print_info("Reading from stdin, writing to stdout")
+        print_info("Press Ctrl+C to stop")
+    else:
+        print_info(f"Listening on {host}:{port}")
+        print_info("Press Ctrl+C to stop")
+
+    # Start serving
+    await server.serve(transport=transport)
+
+
+@app.command()
+def serve(
+    host: Annotated[
+        str,
+        typer.Option(
+            "--host",
+            "-h",
+            help="Host to bind to.",
+        ),
+    ] = "localhost",
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            "-p",
+            help="Port to bind to.",
+        ),
+    ] = 8080,
+    transport: Annotated[
+        str,
+        typer.Option(
+            "--transport",
+            "-t",
+            help="Transport type: stdio or sse.",
+        ),
+    ] = "stdio",
+) -> None:
+    """Start the MCP server.
+
+    Exposes Ouroboros functionality via Model Context Protocol,
+    allowing Claude Desktop and other MCP clients to interact
+    with Ouroboros.
+
+    Available tools:
+    - ouroboros_execute_seed: Execute a seed specification
+    - ouroboros_session_status: Get session status
+    - ouroboros_query_events: Query event history
+
+    Examples:
+
+        # Start with stdio transport (for Claude Desktop)
+        ouroboros mcp serve
+
+        # Start with SSE transport on custom port
+        ouroboros mcp serve --transport sse --port 9000
+    """
+    try:
+        asyncio.run(_run_mcp_server(host, port, transport))
+    except KeyboardInterrupt:
+        print_info("\nMCP Server stopped")
+    except ImportError as e:
+        print_error(f"MCP dependencies not installed: {e}")
+        print_info("Install with: uv add mcp")
+        raise typer.Exit(1) from e
+
+
+@app.command()
+def info() -> None:
+    """Show MCP server information and available tools."""
+    from ouroboros.mcp.server.adapter import create_ouroboros_server
+    from ouroboros.mcp.tools.definitions import OUROBOROS_TOOLS
+
+    from ouroboros.cli.formatters import console
+
+    # Create server
+    server = create_ouroboros_server(
+        name="ouroboros-mcp",
+        version="1.0.0",
+    )
+
+    # Register tools
+    for tool in OUROBOROS_TOOLS:
+        server.register_tool(tool)
+
+    server_info = server.info
+
+    console.print()
+    console.print("[bold]MCP Server Information[/bold]")
+    console.print(f"  Name: {server_info.name}")
+    console.print(f"  Version: {server_info.version}")
+    console.print()
+
+    console.print("[bold]Capabilities[/bold]")
+    console.print(f"  Tools: {server_info.capabilities.tools}")
+    console.print(f"  Resources: {server_info.capabilities.resources}")
+    console.print(f"  Prompts: {server_info.capabilities.prompts}")
+    console.print()
+
+    console.print("[bold]Available Tools[/bold]")
+    for tool in server_info.tools:
+        console.print(f"  [green]{tool.name}[/green]")
+        console.print(f"    {tool.description}")
+        if tool.parameters:
+            console.print("    Parameters:")
+            for param in tool.parameters:
+                required = "[red]*[/red]" if param.required else ""
+                console.print(f"      - {param.name}{required}: {param.description}")
+        console.print()
+
+
+__all__ = ["app"]

ouroboros/cli/commands/run.py

@@ -8,13 +8,16 @@ from __future__ import annotations
 
 import asyncio
 from pathlib import Path
-from typing import Annotated
+from typing import TYPE_CHECKING, Annotated, Any
 
 import typer
 import yaml
 
+if TYPE_CHECKING:
+    from ouroboros.mcp.client.manager import MCPClientManager
+
 from ouroboros.cli.formatters import console
-from ouroboros.cli.formatters.panels import print_error, print_info, print_success
+from ouroboros.cli.formatters.panels import print_error, print_info, print_success, print_warning
 from ouroboros.core.security import InputValidator
 
 app = typer.Typer(
@@ -24,7 +27,7 @@ app = typer.Typer(
 )
 
 
-def _load_seed_from_yaml(seed_file: Path) -> dict:
+def _load_seed_from_yaml(seed_file: Path) -> dict[str, Any]:
     """Load seed configuration from YAML file.
 
     Args:
@@ -45,21 +48,88 @@ def _load_seed_from_yaml(seed_file: Path) -> dict:
 
     try:
         with open(seed_file) as f:
-            return yaml.safe_load(f)
+            data: dict[str, Any] = yaml.safe_load(f)
+            return data
     except Exception as e:
         print_error(f"Failed to load seed file: {e}")
         raise typer.Exit(1) from e
 
 
+async def _initialize_mcp_manager(
+    config_path: Path,
+    tool_prefix: str,
+) -> "MCPClientManager | None":
+    """Initialize MCPClientManager from config file.
+
+    Args:
+        config_path: Path to MCP config YAML.
+        tool_prefix: Prefix to add to MCP tool names.
+
+    Returns:
+        Configured MCPClientManager or None on error.
+    """
+    from ouroboros.mcp.client.manager import MCPClientManager
+    from ouroboros.orchestrator.mcp_config import load_mcp_config
+
+    # Load configuration
+    result = load_mcp_config(config_path)
+    if result.is_err:
+        print_error(f"Failed to load MCP config: {result.error}")
+        return None
+
+    config = result.value
+
+    # Create manager with connection settings
+    manager = MCPClientManager(
+        max_retries=config.connection.retry_attempts,
+        health_check_interval=config.connection.health_check_interval,
+        default_timeout=config.connection.timeout_seconds,
+    )
+
+    # Add all servers
+    for server_config in config.servers:
+        add_result = await manager.add_server(server_config)
+        if add_result.is_err:
+            print_warning(f"Failed to add MCP server '{server_config.name}': {add_result.error}")
+        else:
+            print_info(f"Added MCP server: {server_config.name}")
+
+    # Connect to all servers
+    if manager.servers:
+        print_info("Connecting to MCP servers...")
+        connect_results = await manager.connect_all()
+
+        connected_count = 0
+        for server_name, connect_result in connect_results.items():
+            if connect_result.is_ok:
+                server_info = connect_result.value
+                print_success(f"  Connected to '{server_name}' ({len(server_info.tools)} tools)")
+                connected_count += 1
+            else:
+                print_warning(f"  Failed to connect to '{server_name}': {connect_result.error}")
+
+        if connected_count == 0:
+            print_warning("No MCP servers connected. Continuing without external tools.")
+            return None
+
+        print_info(f"Connected to {connected_count}/{len(manager.servers)} MCP servers")
+
+    return manager
+
+
 async def _run_orchestrator(
     seed_file: Path,
     resume_session: str | None = None,
+    mcp_config: Path | None = None,
+    mcp_tool_prefix: str = "",
 ) -> None:
     """Run workflow via orchestrator mode (Claude Agent SDK).
 
     Args:
         seed_file: Path to seed YAML file.
         resume_session: Optional session ID to resume.
+        mcp_config: Optional path to MCP config file.
+        mcp_tool_prefix: Prefix for MCP tool names.
     """
     from ouroboros.core.seed import Seed
     from ouroboros.orchestrator import ClaudeAgentAdapter, OrchestratorRunner
@@ -77,6 +147,12 @@ async def _run_orchestrator(
     print_info(f"Loaded seed: {seed.goal[:80]}...")
     print_info(f"Acceptance criteria: {len(seed.acceptance_criteria)}")
 
+    # Initialize MCP manager if config provided
+    mcp_manager = None
+    if mcp_config:
+        print_info(f"Loading MCP configuration from: {mcp_config}")
+        mcp_manager = await _initialize_mcp_manager(mcp_config, mcp_tool_prefix)
+
     # Initialize components
     import os
     db_path = os.path.expanduser("~/.ouroboros/ouroboros.db")
@@ -85,32 +161,44 @@ async def _run_orchestrator(
     await event_store.initialize()
 
     adapter = ClaudeAgentAdapter()
-    runner = OrchestratorRunner(adapter, event_store, console)
+    runner = OrchestratorRunner(
+        adapter,
+        event_store,
+        console,
+        mcp_manager=mcp_manager,
+        mcp_tool_prefix=mcp_tool_prefix,
+    )
 
     # Execute
-    if resume_session:
-        print_info(f"Resuming session: {resume_session}")
-        result = await runner.resume_session(resume_session, seed)
-    else:
-        print_info("Starting new orchestrator execution...")
-        result = await runner.execute_seed(seed)
-
-    # Handle result
-    if result.is_ok:
-        res = result.value
-        if res.success:
-            print_success("Execution completed successfully!")
-            print_info(f"Session ID: {res.session_id}")
-            print_info(f"Messages processed: {res.messages_processed}")
-            print_info(f"Duration: {res.duration_seconds:.1f}s")
+    try:
+        if resume_session:
+            print_info(f"Resuming session: {resume_session}")
+            result = await runner.resume_session(resume_session, seed)
+        else:
+            print_info("Starting new orchestrator execution...")
+            result = await runner.execute_seed(seed)
+
+        # Handle result
+        if result.is_ok:
+            res = result.value
+            if res.success:
+                print_success("Execution completed successfully!")
+                print_info(f"Session ID: {res.session_id}")
+                print_info(f"Messages processed: {res.messages_processed}")
+                print_info(f"Duration: {res.duration_seconds:.1f}s")
+            else:
+                print_error("Execution failed")
+                print_info(f"Session ID: {res.session_id}")
+                console.print(f"[dim]Error: {res.final_message[:200]}[/dim]")
+                raise typer.Exit(1)
         else:
-            print_error("Execution failed")
-            print_info(f"Session ID: {res.session_id}")
-            console.print(f"[dim]Error: {res.final_message[:200]}[/dim]")
+            print_error(f"Orchestrator error: {result.error}")
             raise typer.Exit(1)
-    else:
-        print_error(f"Orchestrator error: {result.error}")
-        raise typer.Exit(1)
+    finally:
+        # Cleanup MCP connections
+        if mcp_manager:
+            print_info("Disconnecting MCP servers...")
+            await mcp_manager.disconnect_all()
 
 
 @app.command()
@@ -141,6 +229,20 @@ def workflow(
             help="Resume a previous orchestrator session by ID.",
         ),
     ] = None,
+    mcp_config: Annotated[
+        Path | None,
+        typer.Option(
+            "--mcp-config",
+            help="Path to MCP client configuration YAML file for external tool integration.",
+        ),
+    ] = None,
+    mcp_tool_prefix: Annotated[
+        str,
+        typer.Option(
+            "--mcp-tool-prefix",
+            help="Prefix to add to all MCP tool names (e.g., 'mcp_').",
+        ),
+    ] = "",
     dry_run: Annotated[
         bool,
         typer.Option("--dry-run", "-n", help="Validate seed without executing."),
@@ -156,6 +258,24 @@ def workflow(
 
     Use --orchestrator to execute via Claude Agent SDK (Epic 8).
     Use --resume with --orchestrator to continue a previous session.
+    Use --mcp-config to connect to external MCP servers for additional tools.
+
+    MCP Configuration File Format (YAML):
+
+        mcp_servers:
+          - name: "filesystem"
+            transport: "stdio"
+            command: "npx"
+            args: ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
+          - name: "github"
+            transport: "stdio"
+            command: "npx"
+            args: ["-y", "@anthropic/mcp-server-github"]
+            env:
+              GITHUB_TOKEN: "${GITHUB_TOKEN}"
+        connection:
+          timeout_seconds: 30
+          retry_attempts: 3
 
     Examples:
 
@@ -165,9 +285,22 @@ def workflow(
         # Orchestrator mode (Claude Agent SDK)
         ouroboros run workflow --orchestrator seed.yaml
 
+        # With MCP server integration
+        ouroboros run workflow --orchestrator --mcp-config mcp.yaml seed.yaml
+
+        # With MCP tool prefix
+        ouroboros run workflow -o --mcp-config mcp.yaml --mcp-tool-prefix "ext_" seed.yaml
+
         # Resume a previous orchestrator session
         ouroboros run workflow --orchestrator --resume orch_abc123 seed.yaml
     """
+    # Validate MCP config requires orchestrator mode
+    if mcp_config and not orchestrator and not resume_session:
+        print_warning(
+            "--mcp-config requires --orchestrator flag. Enabling orchestrator mode."
+        )
+        orchestrator = True
+
     if orchestrator or resume_session:
         # Orchestrator mode
         if resume_session and not orchestrator:
@@ -175,7 +308,12 @@ def workflow(
                 "[yellow]Warning: --resume requires --orchestrator flag. "
                 "Enabling orchestrator mode.[/yellow]"
             )
-        asyncio.run(_run_orchestrator(seed_file, resume_session))
+        asyncio.run(_run_orchestrator(
+            seed_file,
+            resume_session,
+            mcp_config,
+            mcp_tool_prefix,
+        ))
     else:
         # Standard workflow (placeholder)
         print_info(f"Would execute workflow from: {seed_file}")

ouroboros/cli/main.py

@@ -9,7 +9,7 @@ from typing import Annotated
 import typer
 
 from ouroboros import __version__
-from ouroboros.cli.commands import config, init, run, status
+from ouroboros.cli.commands import config, init, mcp, run, status
 from ouroboros.cli.formatters import console
 
 # Create the main Typer app
@@ -25,6 +25,7 @@ app.add_typer(init.app, name="init")
 app.add_typer(run.app, name="run")
 app.add_typer(config.app, name="config")
 app.add_typer(status.app, name="status")
+app.add_typer(mcp.app, name="mcp")
 
 
 def version_callback(value: bool) -> None: