ouroboros-ai 0.1.1__tar.gz → 0.2.0__tar.gz

ouroboros_ai-0.2.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-01-27
+
+### Added
+
+#### Security Module (`ouroboros.core.security`)
+- New security utilities module with comprehensive protection features
+- **API Key Management**
+  - `mask_api_key()` - Safely mask API keys for logging (shows only last 4 chars)
+  - `validate_api_key_format()` - Basic format validation for API keys
+- **Sensitive Data Detection**
+  - `is_sensitive_field()` - Detect sensitive field names (api_key, password, token, etc.)
+  - `is_sensitive_value()` - Detect values that look like secrets
+  - `mask_sensitive_value()` - Mask potentially sensitive values
+  - `sanitize_for_logging()` - Create sanitized copies of dicts for safe logging
+- **Input Validation**
+  - `InputValidator` class with size limits for DoS prevention:
+    - `MAX_INITIAL_CONTEXT_LENGTH` = 50KB
+    - `MAX_USER_RESPONSE_LENGTH` = 10KB
+    - `MAX_SEED_FILE_SIZE` = 1MB
+    - `MAX_LLM_RESPONSE_LENGTH` = 100KB
+
+#### Logging Security
+- Automatic sensitive data masking in structlog processor chain
+- API keys, passwords, tokens are now automatically redacted in all log outputs
+- Nested dictionaries are recursively sanitized
+- Pattern-based detection for values starting with `sk-`, `pk-`, `Bearer`, etc.
+
+### Changed
+
+#### Interview Engine
+- Input validation now uses `InputValidator` for consistent size limits
+- `start_interview()` validates initial context length
+- `record_response()` validates user response length
+
+#### LiteLLM Adapter
+- LLM responses are now validated and truncated if exceeding size limits
+- Warning logged when response truncation occurs
+
+#### CLI Run Command
+- Seed file size is now validated before loading
+- Protection against oversized seed files
+
+### Security
+
+- **API Key Management**: Keys are masked in logs, showing only provider prefix and last 4 characters
+- **Input Validation**: All external inputs have size limits to prevent DoS attacks
+- **Log Sanitization**: Sensitive data is automatically masked in all log outputs
+- **Credentials Protection**: `credentials.yaml` continues to use chmod 600 permissions
+
+### Tests
+
+- Added comprehensive test suite for security module (39 tests)
+- Added sensitive data masking tests for logging module (5 tests)
+- All 1341 tests passing
+
+## [0.1.1] - 2026-01-15
+
+### Added
+- Initial release with core Ouroboros workflow system
+- Big Bang (Phase 0) - Interview and Seed generation
+- PAL Router (Phase 1) - Progressive Adaptive LLM selection
+- Double Diamond (Phase 2) - Execution engine
+- Resilience (Phase 3) - Stagnation detection and lateral thinking
+- Evaluation (Phase 4) - Mechanical, semantic, and consensus evaluation
+- Secondary Loop (Phase 5) - TODO registry and batch scheduler
+- Orchestrator (Epic 8) - Claude Agent SDK integration
+- CLI interface with Typer
+- Event sourcing with SQLite persistence
+- Structured logging with structlog
+
+### Fixed
+- Various bug fixes and stability improvements
+
+## [0.1.0] - 2026-01-01
+
+### Added
+- Initial project structure
+- Core types and error hierarchy
+- Basic configuration system

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.1.1
+Version: 0.2.0
 Summary: Self-Improving AI Workflow System
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -52,7 +52,7 @@ Description-Content-Type: text/markdown
 <br/>
 
 <p align="center">
-  <code>73 modules</code> · <code>1,292 tests</code> · <code>97%+ coverage</code>
+  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
 </p>
 
 <br/>
@@ -506,6 +506,36 @@ uv run ouroboros status health
 
 <br/>
 
+## ◈ Security
+
+<br/>
+
+Ouroboros includes built-in security features:
+
+| Feature | Description |
+|---------|-------------|
+| **API Key Masking** | Keys are automatically masked in logs (`sk-...xxxx`) |
+| **Log Sanitization** | Sensitive fields (password, token, secret) are redacted |
+| **Input Validation** | Size limits prevent DoS attacks (50KB context, 1MB seed files) |
+| **Credentials Protection** | `credentials.yaml` uses chmod 600 permissions |
+
+```python
+from ouroboros.core import mask_api_key, sanitize_for_logging
+
+# Mask API keys for display
+masked = mask_api_key("sk-1234567890abcdef")  # "sk-...cdef"
+
+# Sanitize dicts before logging
+safe_data = sanitize_for_logging({"api_key": "sk-secret", "name": "test"})
+# {"api_key": "<REDACTED>", "name": "test"}
+```
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Development
 
 <br/>

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/README.md

@@ -32,7 +32,7 @@
 <br/>
 
 <p align="center">
-  <code>73 modules</code> · <code>1,292 tests</code> · <code>97%+ coverage</code>
+  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
 </p>
 
 <br/>
@@ -486,6 +486,36 @@ uv run ouroboros status health
 
 <br/>
 
+## ◈ Security
+
+<br/>
+
+Ouroboros includes built-in security features:
+
+| Feature | Description |
+|---------|-------------|
+| **API Key Masking** | Keys are automatically masked in logs (`sk-...xxxx`) |
+| **Log Sanitization** | Sensitive fields (password, token, secret) are redacted |
+| **Input Validation** | Size limits prevent DoS attacks (50KB context, 1MB seed files) |
+| **Credentials Protection** | `credentials.yaml` uses chmod 600 permissions |
+
+```python
+from ouroboros.core import mask_api_key, sanitize_for_logging
+
+# Mask API keys for display
+masked = mask_api_key("sk-1234567890abcdef")  # "sk-...cdef"
+
+# Sanitize dicts before logging
+safe_data = sanitize_for_logging({"api_key": "sk-secret", "name": "test"})
+# {"api_key": "<REDACTED>", "name": "test"}
+```
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Development
 
 <br/>

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ouroboros-ai"
-version = "0.1.1"
+version = "0.2.0"
 description = "Self-Improving AI Workflow System"
 readme = "README.md"
 authors = [

ouroboros_ai-0.2.0/src/ouroboros/__init__.py

@@ -0,0 +1,28 @@
+"""Ouroboros - Self-Improving AI Workflow System.
+
+A workflow system that uses Socratic questioning and ontological analysis
+to transform ambiguous requirements into executable specifications.
+
+Example:
+    # Using CLI
+    ouroboros init start "I want to build a task management CLI"
+    ouroboros run workflow seed.yaml
+
+    # Using Python
+    from ouroboros.core import Result, ValidationError
+    from ouroboros.bigbang import InterviewEngine
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__", "main"]
+
+
+def main() -> None:
+    """Main entry point for the Ouroboros CLI.
+
+    This function invokes the Typer app from ouroboros.cli.main.
+    """
+    from ouroboros.cli.main import app
+
+    app()

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/src/ouroboros/bigbang/ambiguity.py

@@ -36,6 +36,9 @@ DEFAULT_MODEL = "openrouter/google/gemini-2.0-flash-001"
 # Temperature for reproducible scoring
 SCORING_TEMPERATURE = 0.1
 
+# Maximum token limit to prevent cost explosion
+MAX_TOKEN_LIMIT = 8192
+
 
 class ComponentScore(BaseModel):
     """Individual component score with justification.
@@ -106,6 +109,17 @@ class AmbiguityScorer:
     Uses LLM to evaluate clarity of goals, constraints, and success criteria
     from interview conversation, producing reproducible scores.
 
+    Uses adaptive token allocation: starts with `initial_max_tokens` and
+    doubles on truncation up to `MAX_TOKEN_LIMIT`. Retries up to `max_retries`
+    times on both provider errors and parse failures.
+
+    Attributes:
+        llm_adapter: The LLM adapter for completions.
+        model: Model identifier to use.
+        temperature: Temperature for reproducibility (default 0.1).
+        initial_max_tokens: Starting token limit (default 2048).
+        max_retries: Maximum retry attempts (default 3).
+
     Example:
         scorer = AmbiguityScorer(llm_adapter=LiteLLMAdapter())
 
@@ -123,7 +137,8 @@ class AmbiguityScorer:
     llm_adapter: LiteLLMAdapter
     model: str = DEFAULT_MODEL
     temperature: float = SCORING_TEMPERATURE
-    max_tokens: int = 2048
+    initial_max_tokens: int = 2048
+    max_retries: int = 3
 
     async def score(
         self, state: InterviewState
@@ -135,6 +150,9 @@ class AmbiguityScorer:
         - Constraints (30% weight)
         - Success criteria (30% weight)
 
+        Uses adaptive token allocation: starts with initial_max_tokens and
+        doubles on parse failure, up to max_retries attempts.
+
         Args:
             state: The interview state to score.
 
@@ -159,57 +177,98 @@ class AmbiguityScorer:
             Message(role=MessageRole.USER, content=user_prompt),
         ]
 
-        config = CompletionConfig(
-            model=self.model,
-            temperature=self.temperature,
-            max_tokens=self.max_tokens,
-        )
-
-        result = await self.llm_adapter.complete(messages, config)
+        current_max_tokens = self.initial_max_tokens
+        last_error: Exception | ProviderError | None = None
+        last_response: str = ""
 
-        if result.is_err:
-            log.warning(
-                "ambiguity.scoring.failed",
-                interview_id=state.interview_id,
-                error=str(result.error),
+        for attempt in range(self.max_retries):
+            config = CompletionConfig(
+                model=self.model,
+                temperature=self.temperature,
+                max_tokens=current_max_tokens,
             )
-            return Result.err(result.error)
-
-        # Parse the LLM response into scores
-        try:
-            breakdown = self._parse_scoring_response(result.value.content)
-            overall_score = self._calculate_overall_score(breakdown)
 
-            ambiguity_score = AmbiguityScore(
-                overall_score=overall_score,
-                breakdown=breakdown,
-            )
+            result = await self.llm_adapter.complete(messages, config)
+
+            # Fix #3: Retry on provider errors (rate limits, transient failures)
+            if result.is_err:
+                last_error = result.error
+                log.warning(
+                    "ambiguity.scoring.provider_error_retrying",
+                    interview_id=state.interview_id,
+                    error=str(result.error),
+                    attempt=attempt + 1,
+                    max_retries=self.max_retries,
+                )
+                continue
 
-            log.info(
-                "ambiguity.scoring.completed",
-                interview_id=state.interview_id,
-                overall_score=overall_score,
-                is_ready_for_seed=ambiguity_score.is_ready_for_seed,
-                goal_clarity=breakdown.goal_clarity.clarity_score,
-                constraint_clarity=breakdown.constraint_clarity.clarity_score,
-                success_criteria_clarity=breakdown.success_criteria_clarity.clarity_score,
-            )
+            # Parse the LLM response into scores
+            try:
+                breakdown = self._parse_scoring_response(result.value.content)
+                overall_score = self._calculate_overall_score(breakdown)
 
-            return Result.ok(ambiguity_score)
+                ambiguity_score = AmbiguityScore(
+                    overall_score=overall_score,
+                    breakdown=breakdown,
+                )
 
-        except (ValueError, KeyError) as e:
-            log.warning(
-                "ambiguity.scoring.parse_failed",
-                interview_id=state.interview_id,
-                error=str(e),
-                response=result.value.content[:500],
-            )
-            return Result.err(
-                ProviderError(
-                    f"Failed to parse scoring response: {e}",
-                    details={"response_preview": result.value.content[:200]},
+                log.info(
+                    "ambiguity.scoring.completed",
+                    interview_id=state.interview_id,
+                    overall_score=overall_score,
+                    is_ready_for_seed=ambiguity_score.is_ready_for_seed,
+                    goal_clarity=breakdown.goal_clarity.clarity_score,
+                    constraint_clarity=breakdown.constraint_clarity.clarity_score,
+                    success_criteria_clarity=breakdown.success_criteria_clarity.clarity_score,
+                    tokens_used=current_max_tokens,
+                    attempt=attempt + 1,
                 )
+
+                return Result.ok(ambiguity_score)
+
+            except (ValueError, KeyError) as e:
+                last_error = e
+                last_response = result.value.content
+
+                # Fix #2: Only increase tokens if response was truncated
+                is_truncated = result.value.finish_reason == "length"
+
+                if is_truncated:
+                    # Fix #1: Cap token growth with MAX_TOKEN_LIMIT
+                    next_tokens = min(current_max_tokens * 2, MAX_TOKEN_LIMIT)
+                    log.warning(
+                        "ambiguity.scoring.truncated_retrying",
+                        interview_id=state.interview_id,
+                        error=str(e),
+                        attempt=attempt + 1,
+                        current_tokens=current_max_tokens,
+                        next_tokens=next_tokens,
+                    )
+                    current_max_tokens = next_tokens
+                else:
+                    # Format error without truncation - retry with same tokens
+                    log.warning(
+                        "ambiguity.scoring.format_error_retrying",
+                        interview_id=state.interview_id,
+                        error=str(e),
+                        attempt=attempt + 1,
+                        finish_reason=result.value.finish_reason,
+                    )
+
+        # All retries exhausted
+        log.warning(
+            "ambiguity.scoring.failed",
+            interview_id=state.interview_id,
+            error=str(last_error),
+            response=last_response[:500] if last_response else None,
+            max_retries_exhausted=True,
+        )
+        return Result.err(
+            ProviderError(
+                f"Failed to parse scoring response after {self.max_retries} attempts: {last_error}",
+                details={"response_preview": last_response[:200] if last_response else None},
             )
+        )
 
     def _build_interview_context(self, state: InterviewState) -> str:
         """Build context string from interview state.
@@ -254,15 +313,17 @@ Evaluate three components:
 
 For each component, provide:
 - A clarity score between 0.0 (completely unclear) and 1.0 (perfectly clear)
-- A brief justification explaining the score
+- A brief justification (1-2 sentences max) explaining the score
+
+IMPORTANT: You MUST provide ALL six fields below. Keep justifications concise.
 
 Respond in this exact format:
 GOAL_CLARITY_SCORE: <score>
-GOAL_CLARITY_JUSTIFICATION: <justification>
+GOAL_CLARITY_JUSTIFICATION: <justification in 1-2 sentences>
 CONSTRAINT_CLARITY_SCORE: <score>
-CONSTRAINT_CLARITY_JUSTIFICATION: <justification>
+CONSTRAINT_CLARITY_JUSTIFICATION: <justification in 1-2 sentences>
 SUCCESS_CRITERIA_CLARITY_SCORE: <score>
-SUCCESS_CRITERIA_CLARITY_JUSTIFICATION: <justification>
+SUCCESS_CRITERIA_CLARITY_JUSTIFICATION: <justification in 1-2 sentences>
 
 Be strict in your evaluation. Scores above 0.8 require very specific, measurable requirements."""
 

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/src/ouroboros/bigbang/interview.py

@@ -17,6 +17,7 @@ from pydantic import BaseModel, Field
 import structlog
 
 from ouroboros.core.errors import ProviderError, ValidationError
+from ouroboros.core.security import InputValidator
 from ouroboros.core.types import Result
 from ouroboros.providers.base import (
     CompletionConfig,
@@ -186,9 +187,11 @@ class InterviewEngine:
         Returns:
             Result containing the new InterviewState or ValidationError.
         """
-        if not initial_context.strip():
+        # Validate initial context with security limits
+        is_valid, error_msg = InputValidator.validate_initial_context(initial_context)
+        if not is_valid:
             return Result.err(
-                ValidationError("Initial context cannot be empty", field="initial_context")
+                ValidationError(error_msg, field="initial_context")
             )
 
         if interview_id is None:
@@ -285,9 +288,11 @@ class InterviewEngine:
         Returns:
             Result containing updated state or ValidationError.
         """
-        if not user_response.strip():
+        # Validate user response with security limits
+        is_valid, error_msg = InputValidator.validate_user_response(user_response)
+        if not is_valid:
             return Result.err(
-                ValidationError("User response cannot be empty", field="user_response")
+                ValidationError(error_msg, field="user_response")
             )
 
         if state.is_complete:

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/src/ouroboros/cli/commands/run.py

@@ -15,6 +15,7 @@ import yaml
 
 from ouroboros.cli.formatters import console
 from ouroboros.cli.formatters.panels import print_error, print_info, print_success
+from ouroboros.core.security import InputValidator
 
 app = typer.Typer(
     name="run",
@@ -33,8 +34,15 @@ def _load_seed_from_yaml(seed_file: Path) -> dict:
         Seed configuration dictionary.
 
     Raises:
-        typer.Exit: If file cannot be loaded.
+        typer.Exit: If file cannot be loaded or exceeds size limit.
     """
+    # Security: Validate file size to prevent DoS
+    file_size = seed_file.stat().st_size
+    is_valid, error_msg = InputValidator.validate_seed_file_size(file_size)
+    if not is_valid:
+        print_error(f"Seed file validation failed: {error_msg}")
+        raise typer.Exit(1)
+
     try:
         with open(seed_file) as f:
             return yaml.safe_load(f)

{ouroboros_ai-0.1.1 → ouroboros_ai-0.2.0}/src/ouroboros/core/__init__.py

@@ -27,6 +27,12 @@ from ouroboros.core.seed import (
     Seed,
     SeedMetadata,
 )
+from ouroboros.core.security import (
+    InputValidator,
+    mask_api_key,
+    sanitize_for_logging,
+    validate_api_key_format,
+)
 from ouroboros.core.types import CostUnits, DriftScore, EventPayload, Result
 
 __all__ = [
@@ -59,4 +65,9 @@ __all__ = [
     "compress_context",
     "compress_context_with_llm",
     "create_filtered_context",
+    # Security utilities
+    "InputValidator",
+    "mask_api_key",
+    "validate_api_key_format",
+    "sanitize_for_logging",
 ]