ouroboros-ai 0.2.3__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/interview.py

@@ -1,7 +1,7 @@
 """Interactive interview engine for requirement clarification.
 
 This module implements the interview protocol that refines vague ideas into
-clear requirements through iterative questioning (max 10 rounds).
+clear requirements through iterative questioning. Users control when to stop.
 """
 
 from collections.abc import Iterator
@@ -52,10 +52,17 @@ def _file_lock(file_path: Path, exclusive: bool = True) -> Iterator[None]:
 
 log = structlog.get_logger()
 
-MAX_INTERVIEW_ROUNDS = 10
+# Interview round constants
+MIN_ROUNDS_BEFORE_EARLY_EXIT = 3  # Must complete at least 3 rounds
+SOFT_LIMIT_WARNING_THRESHOLD = 15  # Warn about diminishing returns after this
+DEFAULT_INTERVIEW_ROUNDS = 10  # Reference value for prompts (not enforced)
+
 # Default model moved to config.models.ClarificationConfig.default_model
 _FALLBACK_MODEL = "openrouter/google/gemini-2.0-flash-001"
 
+# Legacy alias for backward compatibility
+MAX_INTERVIEW_ROUNDS = DEFAULT_INTERVIEW_ROUNDS
+
 
 class InterviewStatus(StrEnum):
     """Status of the interview process."""
@@ -69,13 +76,13 @@ class InterviewRound(BaseModel):
     """A single round of interview questions and responses.
 
     Attributes:
-        round_number: 1-based round number (1 to MAX_INTERVIEW_ROUNDS).
+        round_number: 1-based round number (no upper limit - user controls).
         question: The question asked by the system.
         user_response: The user's response (None if not yet answered).
         timestamp: When this round was created.
     """
 
-    round_number: int = Field(ge=1, le=MAX_INTERVIEW_ROUNDS)
+    round_number: int = Field(ge=1)  # No upper limit - user decides when to stop
     question: str
     user_response: str | None = None
     timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
@@ -107,11 +114,8 @@ class InterviewState(BaseModel):
 
     @property
     def is_complete(self) -> bool:
-        """Check if interview has reached max rounds or is marked complete."""
-        return (
-            self.status == InterviewStatus.COMPLETED
-            or len(self.rounds) >= MAX_INTERVIEW_ROUNDS
-        )
+        """Check if interview is marked complete (user-controlled)."""
+        return self.status == InterviewStatus.COMPLETED
 
     def mark_updated(self) -> None:
         """Update the updated_at timestamp."""
@@ -321,14 +325,8 @@ class InterviewEngine:
             response_length=len(user_response),
         )
 
-        # Check if we've reached max rounds
-        if len(state.rounds) >= MAX_INTERVIEW_ROUNDS:
-            state.status = InterviewStatus.COMPLETED
-            log.info(
-                "interview.max_rounds_reached",
-                interview_id=state.interview_id,
-                total_rounds=len(state.rounds),
-            )
+        # Note: No auto-complete on round limit. User controls when to stop.
+        # CLI handles prompting user to continue after each round.
 
         return Result.ok(state)
 
@@ -437,7 +435,7 @@ class InterviewEngine:
         Returns:
             The system prompt.
         """
-        round_info = f"Round {state.current_round_number} of {MAX_INTERVIEW_ROUNDS}"
+        round_info = f"Round {state.current_round_number}"
 
         return f"""You are an expert requirements engineer conducting an interview to refine vague ideas into clear, executable requirements.
 

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
 """