ouroboros-ai 0.2.3__tar.gz → 0.3.0__tar.gz

{ouroboros_ai-0.2.3 → ouroboros_ai-0.3.0}/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.3.0] - 2026-01-28
+
+### Added
+
+#### Documentation
+- **CLI Reference** (`docs/cli-reference.md`) - Complete command reference with examples
+- **Prerequisites section** in README with Python 3.14+ requirement
+- **Contributing section** with links to Issues and Discussions
+- **OSS badges** - PyPI version, Python version, License
+
+#### Interview System
+- **Tiered confirmation system** for interview rounds:
+  - Rounds 1-3: Auto-continue (minimum context gathering)
+  - Rounds 4-15: Ask "Continue?" after each round
+  - Rounds 16+: Ask "Continue?" with diminishing returns warning
+- **No hard round limit** - User controls when to stop
+- New constants: `MIN_ROUNDS_BEFORE_EARLY_EXIT`, `SOFT_LIMIT_WARNING_THRESHOLD`
+
+### Changed
+
+#### Interview Engine
+- Removed `MAX_INTERVIEW_ROUNDS` hard limit (was 10)
+- `is_complete` now only checks status (user-controlled completion)
+- `record_response()` no longer auto-completes at max rounds
+- System prompt simplified to show "Round N" instead of "Round N of 10"
+
+#### CLI Init Command
+- Extracted `_run_interview_loop()` helper to eliminate code duplication (~60 lines)
+- State saved immediately after status mutation for consistency
+- Updated welcome message to reflect no round limit
+
+### Removed
+- Korean-language requirement documents (`requirement/` folder)
+- Hard round limit enforcement in interview engine
+
+### Fixed
+- Code duplication in init.py interview continuation flow
+
 ## [0.2.0] - 2026-01-27
 
 ### Added

{ouroboros_ai-0.2.3 → ouroboros_ai-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.2.3
+Version: 0.3.0
 Summary: Self-Improving AI Workflow System
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -41,18 +41,26 @@ Description-Content-Type: text/markdown
   <em>The serpent that devours itself to be reborn anew.</em>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.14+-blue" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+
 <p align="center">
   <a href="#-philosophy">Philosophy</a> •
   <a href="#-the-six-phases">Phases</a> •
   <a href="#-architecture">Architecture</a> •
+  <a href="#-prerequisites">Prerequisites</a> •
   <a href="#-quick-start">Start</a> •
-  <a href="#-the-personas-lateral-thinking-agents">Personas</a>
+  <a href="#-roadmap">Roadmap</a> •
+  <a href="#-contributing">Contributing</a>
 </p>
 
 <br/>
 
 <p align="center">
-  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code> · <code>v0.2.x</code>
 </p>
 
 <br/>
@@ -352,7 +360,7 @@ src/ouroboros/
 
 <br/>
 
-**작동 방식**: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
+**How it works**: Stagnation Detection (4 patterns) → Persona Rotation → Retry with fresh perspective
 
 <br/>
 
@@ -415,6 +423,22 @@ not to restart, but to **re-crystallize** with new understanding.
 
 <br/>
 
+## ◈ Prerequisites
+
+<br/>
+
+| Requirement | Description |
+|-------------|-------------|
+| **Python 3.14+** | Required (uses latest language features) |
+| **Claude Code Max Plan** | For orchestrator mode (no API key needed) |
+| **OR API Key** | OpenRouter, Anthropic, or OpenAI for LiteLLM mode |
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Installation
 
 <br/>
@@ -476,7 +500,7 @@ uv run ouroboros init start "I want to build a task management CLI"
 uv run ouroboros status health
 ```
 
-> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)**
+> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)** | **[CLI Reference](docs/cli-reference.md)**
 
 <br/>
 
@@ -563,22 +587,49 @@ uv run ruff format src/
 
 <br/>
 
+## ◈ Contributing
+
+<br/>
+
+Contributions are welcome! Please see:
+
+- **Issues**: [GitHub Issues](https://github.com/Q00/ouroboros/issues) for bugs and feature requests
+- **Discussions**: [GitHub Discussions](https://github.com/Q00/ouroboros/discussions) for questions and ideas
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Roadmap
 
 <br/>
 
+### Completed
+
 ```
-[■■■■■■■■■■] Epic 0  Foundation
-[■■■■■■■■■■] Epic 1  Big Bang
-[■■■■■■■■■■] Epic 2  PAL Router
-[■■■■■■■■■■] Epic 3  Double Diamond
-[■■■■■■■■■■] Epic 4  Resilience
-[■■■■■■■■■■] Epic 5  Evaluation
-[■■■■■■■■■■] Epic 6  Drift Control
-[■■■■■■■■■■] Epic 7  Secondary Loop
-[■■■■■■■■■■] Epic 8  Orchestrator      ✓ Complete
+[■■■■■■■■■■] Epic 0  Foundation          ✓
+[■■■■■■■■■■] Epic 1  Big Bang            ✓
+[■■■■■■■■■■] Epic 2  PAL Router          ✓
+[■■■■■■■■■■] Epic 3  Double Diamond      ✓
+[■■■■■■■■■■] Epic 4  Resilience          ✓
+[■■■■■■■■■■] Epic 5  Evaluation          ✓
+[■■■■■■■■■■] Epic 6  Drift Control       ✓
+[■■■■■■■■■■] Epic 7  Secondary Loop      ✓
+[■■■■■■■■■■] Epic 8  Orchestrator        ✓
 ```
 
+### Upcoming
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Worker MCP** | MCP server for distributed task execution | Planned |
+| **TUI Enhancement** | Rich terminal UI with real-time progress | Planned |
+| **AC Tree Visualization** | Interactive acceptance criteria graph | Planned |
+| **Plugin System** | Custom evaluators and personas | Planned |
+| **Web Dashboard** | Execution monitoring and analytics | Planned |
+
 <br/>
 
 ---

{ouroboros_ai-0.2.3 → ouroboros_ai-0.3.0}/README.md

@@ -21,18 +21,26 @@
   <em>The serpent that devours itself to be reborn anew.</em>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ouroboros-ai/"><img src="https://img.shields.io/pypi/v/ouroboros-ai?color=blue" alt="PyPI"></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.14+-blue" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+
 <p align="center">
   <a href="#-philosophy">Philosophy</a> •
   <a href="#-the-six-phases">Phases</a> •
   <a href="#-architecture">Architecture</a> •
+  <a href="#-prerequisites">Prerequisites</a> •
   <a href="#-quick-start">Start</a> •
-  <a href="#-the-personas-lateral-thinking-agents">Personas</a>
+  <a href="#-roadmap">Roadmap</a> •
+  <a href="#-contributing">Contributing</a>
 </p>
 
 <br/>
 
 <p align="center">
-  <code>74 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code>
+  <code>75 modules</code> · <code>1,341 tests</code> · <code>97%+ coverage</code> · <code>v0.2.x</code>
 </p>
 
 <br/>
@@ -332,7 +340,7 @@ src/ouroboros/
 
 <br/>
 
-**작동 방식**: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
+**How it works**: Stagnation Detection (4 patterns) → Persona Rotation → Retry with fresh perspective
 
 <br/>
 
@@ -395,6 +403,22 @@ not to restart, but to **re-crystallize** with new understanding.
 
 <br/>
 
+## ◈ Prerequisites
+
+<br/>
+
+| Requirement | Description |
+|-------------|-------------|
+| **Python 3.14+** | Required (uses latest language features) |
+| **Claude Code Max Plan** | For orchestrator mode (no API key needed) |
+| **OR API Key** | OpenRouter, Anthropic, or OpenAI for LiteLLM mode |
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Installation
 
 <br/>
@@ -456,7 +480,7 @@ uv run ouroboros init start "I want to build a task management CLI"
 uv run ouroboros status health
 ```
 
-> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)**
+> 📖 **[Full Guide: Running with Claude Code](docs/running-with-claude-code.md)** | **[CLI Reference](docs/cli-reference.md)**
 
 <br/>
 
@@ -543,22 +567,49 @@ uv run ruff format src/
 
 <br/>
 
+## ◈ Contributing
+
+<br/>
+
+Contributions are welcome! Please see:
+
+- **Issues**: [GitHub Issues](https://github.com/Q00/ouroboros/issues) for bugs and feature requests
+- **Discussions**: [GitHub Discussions](https://github.com/Q00/ouroboros/discussions) for questions and ideas
+
+<br/>
+
+---
+
+<br/>
+
 ## ◈ Roadmap
 
 <br/>
 
+### Completed
+
 ```
-[■■■■■■■■■■] Epic 0  Foundation
-[■■■■■■■■■■] Epic 1  Big Bang
-[■■■■■■■■■■] Epic 2  PAL Router
-[■■■■■■■■■■] Epic 3  Double Diamond
-[■■■■■■■■■■] Epic 4  Resilience
-[■■■■■■■■■■] Epic 5  Evaluation
-[■■■■■■■■■■] Epic 6  Drift Control
-[■■■■■■■■■■] Epic 7  Secondary Loop
-[■■■■■■■■■■] Epic 8  Orchestrator      ✓ Complete
+[■■■■■■■■■■] Epic 0  Foundation          ✓
+[■■■■■■■■■■] Epic 1  Big Bang            ✓
+[■■■■■■■■■■] Epic 2  PAL Router          ✓
+[■■■■■■■■■■] Epic 3  Double Diamond      ✓
+[■■■■■■■■■■] Epic 4  Resilience          ✓
+[■■■■■■■■■■] Epic 5  Evaluation          ✓
+[■■■■■■■■■■] Epic 6  Drift Control       ✓
+[■■■■■■■■■■] Epic 7  Secondary Loop      ✓
+[■■■■■■■■■■] Epic 8  Orchestrator        ✓
 ```
 
+### Upcoming
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Worker MCP** | MCP server for distributed task execution | Planned |
+| **TUI Enhancement** | Rich terminal UI with real-time progress | Planned |
+| **AC Tree Visualization** | Interactive acceptance criteria graph | Planned |
+| **Plugin System** | Custom evaluators and personas | Planned |
+| **Web Dashboard** | Execution monitoring and analytics | Planned |
+
 <br/>
 
 ---

ouroboros_ai-0.3.0/docs/cli-reference.md

@@ -0,0 +1,379 @@
+# CLI Reference
+
+Complete command reference for the Ouroboros CLI.
+
+## Installation
+
+```bash
+pip install ouroboros-ai
+# or
+uv pip install ouroboros-ai
+```
+
+## Usage
+
+```bash
+ouroboros [OPTIONS] COMMAND [ARGS]...
+```
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-V, --version` | Show version and exit |
+| `--install-completion` | Install shell completion |
+| `--show-completion` | Show shell completion script |
+| `--help` | Show help message |
+
+---
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `init` | Start interactive interview to refine requirements |
+| `run` | Execute Ouroboros workflows |
+| `config` | Manage Ouroboros configuration |
+| `status` | Check Ouroboros system status |
+
+---
+
+## `ouroboros init`
+
+Start interactive interview to refine requirements (Big Bang phase).
+
+### `init start`
+
+Start an interactive interview to transform vague ideas into clear, executable requirements.
+
+```bash
+ouroboros init start [OPTIONS] [CONTEXT]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `CONTEXT` | Initial context or idea (interactive prompt if not provided) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-r, --resume TEXT` | Resume an existing interview by ID |
+| `--state-dir DIRECTORY` | Custom directory for interview state files |
+| `-o, --orchestrator` | Use Claude Code (Max Plan) instead of LiteLLM. No API key required |
+
+**Examples:**
+
+```bash
+# Start with initial idea (LiteLLM - requires API key)
+ouroboros init start "I want to build a task management CLI tool"
+
+# Start with Claude Code (no API key needed)
+ouroboros init start --orchestrator "Build a REST API"
+
+# Resume an interrupted interview
+ouroboros init start --resume interview_20260116_120000
+
+# Interactive mode (prompts for input)
+ouroboros init start
+```
+
+### `init list`
+
+List all interview sessions.
+
+```bash
+ouroboros init list
+```
+
+---
+
+## `ouroboros run`
+
+Execute Ouroboros workflows.
+
+### `run workflow`
+
+Execute a workflow from a seed file.
+
+```bash
+ouroboros run workflow [OPTIONS] SEED_FILE
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `SEED_FILE` | Yes | Path to the seed YAML file |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-o, --orchestrator` | Use Claude Agent SDK for execution (Epic 8 mode) |
+| `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
+| `-n, --dry-run` | Validate seed without executing |
+| `-v, --verbose` | Enable verbose output |
+
+**Examples:**
+
+```bash
+# Standard workflow execution
+ouroboros run workflow seed.yaml
+
+# Orchestrator mode (Claude Agent SDK)
+ouroboros run workflow --orchestrator seed.yaml
+
+# Dry run (validate only)
+ouroboros run workflow --dry-run seed.yaml
+
+# Resume a previous session
+ouroboros run workflow --orchestrator --resume orch_abc123 seed.yaml
+
+# Verbose output
+ouroboros run workflow --orchestrator --verbose seed.yaml
+```
+
+### `run resume`
+
+Resume a paused or failed execution.
+
+```bash
+ouroboros run resume [EXECUTION_ID]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `EXECUTION_ID` | Execution ID to resume (uses latest if not specified) |
+
+> **Note:** For orchestrator sessions, use:
+> ```bash
+> ouroboros run workflow --orchestrator --resume <session_id> seed.yaml
+> ```
+
+---
+
+## `ouroboros config`
+
+Manage Ouroboros configuration.
+
+### `config show`
+
+Display current configuration.
+
+```bash
+ouroboros config show [SECTION]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `SECTION` | Configuration section to display (e.g., `providers`) |
+
+**Examples:**
+
+```bash
+# Show all configuration
+ouroboros config show
+
+# Show only providers section
+ouroboros config show providers
+```
+
+### `config init`
+
+Initialize Ouroboros configuration. Creates default configuration files if they don't exist.
+
+```bash
+ouroboros config init
+```
+
+### `config set`
+
+Set a configuration value.
+
+```bash
+ouroboros config set KEY VALUE
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `KEY` | Yes | Configuration key (dot notation) |
+| `VALUE` | Yes | Value to set |
+
+**Examples:**
+
+```bash
+# Set API key for a provider
+ouroboros config set providers.openai.api_key sk-xxx
+
+# Set nested configuration
+ouroboros config set execution.max_retries 5
+```
+
+### `config validate`
+
+Validate current configuration.
+
+```bash
+ouroboros config validate
+```
+
+---
+
+## `ouroboros status`
+
+Check Ouroboros system status.
+
+### `status health`
+
+Check system health. Verifies database connectivity, provider configuration, and system resources.
+
+```bash
+ouroboros status health
+```
+
+**Example Output:**
+
+```
+┌───────────────┬─────────┐
+│ Database      │   ok    │
+│ Configuration │   ok    │
+│ Providers     │ warning │
+└───────────────┴─────────┘
+```
+
+### `status executions`
+
+List recent executions with status information.
+
+```bash
+ouroboros status executions [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-n, --limit INTEGER` | Number of executions to show (default: 10) |
+| `-a, --all` | Show all executions |
+
+**Examples:**
+
+```bash
+# Show last 10 executions
+ouroboros status executions
+
+# Show last 5 executions
+ouroboros status executions -n 5
+
+# Show all executions
+ouroboros status executions --all
+```
+
+### `status execution`
+
+Show details for a specific execution.
+
+```bash
+ouroboros status execution [OPTIONS] EXECUTION_ID
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `EXECUTION_ID` | Yes | Execution ID to inspect |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-e, --events` | Show execution events |
+
+**Examples:**
+
+```bash
+# Show execution details
+ouroboros status execution exec_abc123
+
+# Show execution with events
+ouroboros status execution --events exec_abc123
+```
+
+---
+
+## Typical Workflows
+
+### Using Claude Code (Recommended)
+
+No API key required - uses your Claude Code Max Plan subscription.
+
+```bash
+# 1. Check system health
+ouroboros status health
+
+# 2. Start interview to create seed
+ouroboros init start --orchestrator "Build a user authentication system"
+
+# 3. Execute the generated seed
+ouroboros run workflow --orchestrator seed.yaml
+```
+
+### Using LiteLLM (External API)
+
+Requires API key (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.)
+
+```bash
+# 1. Initialize configuration
+ouroboros config init
+
+# 2. Set your API key
+ouroboros config set providers.openrouter.api_key $OPENROUTER_API_KEY
+
+# 3. Start interview
+ouroboros init start "Build a REST API for task management"
+
+# 4. Execute workflow
+ouroboros run workflow seed.yaml
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OPENROUTER_API_KEY` | OpenRouter API key for LiteLLM |
+| `ANTHROPIC_API_KEY` | Anthropic API key for LiteLLM |
+| `OPENAI_API_KEY` | OpenAI API key for LiteLLM |
+
+---
+
+## Configuration Files
+
+Ouroboros stores configuration in `~/.ouroboros/`:
+
+| File | Description |
+|------|-------------|
+| `config.yaml` | Main configuration |
+| `credentials.yaml` | API keys (chmod 600) |
+| `ouroboros.db` | SQLite database for event sourcing |
+
+---
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Configuration error |
+| `3` | Validation error |

{ouroboros_ai-0.2.3 → ouroboros_ai-0.3.0}/pyproject.toml

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