ucgen 0.1.0__tar.gz

ucgen-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.pyc
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.ucgen_debug/
+.ucgen_counter
+use-cases/
+.ucgenrc.toml

ucgen-0.1.0/.ucgenrc.toml.example

@@ -0,0 +1,21 @@
+# ucgen configuration example
+# Copy this file to .ucgenrc.toml and customize values.
+
+[defaults]
+provider = "ollama"
+model = "mistral"        # or "qwen3:8b" — better JSON reliability
+output_dir = "./use-cases"
+template = "default"
+id_prefix = "UC"
+temperature = 0.3
+max_tokens = 4000  # increase if sections are truncated,
+                   # decrease if your hardware is slow
+
+[providers]
+ollama_base_url = "http://localhost:11434"
+custom_base_url = ""
+custom_prompts_dir = ""
+
+[hooks]
+on_generate = ""
+on_batch_complete = ""

ucgen-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+## Setup
+
+Requires Python 3.11+ and uv.
+
+pip install uv
+uv sync --extra dev
+uv run pytest tests/ -v
+
+## Linting and type checking
+
+python -m ruff check ucgen/
+python -m ruff format --check ucgen/
+python -m mypy ucgen/ --ignore-missing-imports
+
+## Local models (Ollama)
+
+Recommended models:
+- qwen3:8b   — better structured JSON output, recommended
+- mistral     — lighter, faster, occasional type mismatches
+
+ollama pull qwen3:8b
+ollama pull mistral

ucgen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aureum01
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ucgen-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: ucgen
+Version: 0.1.0
+Summary: Generate structured use case documents from natural language input.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: anthropic>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: openai>=1.40
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: all
+Requires-Dist: mypy>=1.10; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
+Requires-Dist: pytest-mock>=3.12; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: ruff>=0.5; extra == 'all'
+Requires-Dist: types-pyyaml>=6.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: project
+Requires-Dist: pyyaml>=6.0; extra == 'project'
+Description-Content-Type: text/markdown
+
+# ucgen
+
+CLI tool that generates structured Cockburn-style use case documents from natural language using local or cloud LLMs.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-3776AB)
+![License](https://img.shields.io/badge/license-MIT-0a0a0a?labelColor=0a0a0a)
+![Version](https://img.shields.io/badge/version-0.1.0-2563eb)
+![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-6b7280)
+
+## What it does
+
+`ucgen` closes the gap between a rough feature idea and a structured use case specification that developers can review and implement. It runs a staged generation pipeline that produces consistent Cockburn-style sections instead of free-form prose. Output is written as Markdown documents with frontmatter plus self-contained HTML reports for review and sharing.
+
+## Quick start
+
+### With Ollama (free, local)
+
+```bash
+pip install ucgen
+ollama pull qwen3:8b
+ucgen generate "warehouse picker scans barcode to confirm item before adding to shipment"
+```
+
+### With Anthropic
+
+```bash
+pip install ucgen
+export ANTHROPIC_API_KEY=sk-ant-...   # Windows: $env:ANTHROPIC_API_KEY=...
+ucgen generate "warehouse picker scans barcode to confirm item before adding to shipment" --provider anthropic --model claude-sonnet-4-6
+```
+
+## Troubleshooting
+
+- **Provider unavailable:** run `ucgen version` to check provider status.
+- **Anthropic auth errors:** confirm `ANTHROPIC_API_KEY` is set in the same shell session.
+- **Ollama connection errors:** start Ollama with `ollama serve` and verify model exists with `ollama list`.
+- **No report output:** ensure generation completed and rerun with `--report`, or run `ucgen report`.
+
+## Output
+
+For the warehouse picker example, `ucgen` creates a per-use-case folder with Markdown, JSON, and optional single-report HTML.
+
+```text
+use-cases/
+  report.html
+  standalone/
+    UC-2026-0049-warehouse-picker-scans-barcode/
+      UC-2026-0049-warehouse-picker-scans-barcode.md
+      UC-2026-0049-warehouse-picker-scans-barcode.json
+      report.html
+```
+
+- `*.md`: human-readable use case document
+- `*.json`: full structured `UseCaseDocument`
+- `report.html`: self-contained HTML report (single-use-case when generated with `--report`)
+
+## Configuration
+
+Initialize local config:
+
+```bash
+ucgen init
+```
+
+Example `.ucgenrc.toml`:
+
+```toml
+[defaults]
+provider = "ollama"
+model = "qwen3:8b"
+output_dir = "./use-cases"
+template = "default"
+temperature = 0.3
+max_tokens = 4000
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ucgen generate "<idea>"` | Generate one use case |
+| `ucgen generate "<idea>" --report` | Generate one use case and a single report in the UC folder |
+| `ucgen batch <ideas.txt>` | Generate from a text/yaml batch file |
+| `ucgen report` | Build portfolio report from all JSON docs in `output_dir` |
+| `ucgen run` | Generate from `ucgen.yaml` project file |
+| `ucgen status` | Show project generation status |
+| `ucgen validate <path>` | Validate generated markdown files |
+| `ucgen init` | Create `.ucgenrc.toml` |
+| `ucgen init-project "<name>"` | Scaffold `ucgen.yaml` |
+| `ucgen log` | Record a mistake in memory |
+| `ucgen gc` | Archive/graduate memory entries |
+| `ucgen version` | Show version and provider availability |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ucgen-0.1.0/README.md

@@ -0,0 +1,96 @@
+# ucgen
+
+CLI tool that generates structured Cockburn-style use case documents from natural language using local or cloud LLMs.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-3776AB)
+![License](https://img.shields.io/badge/license-MIT-0a0a0a?labelColor=0a0a0a)
+![Version](https://img.shields.io/badge/version-0.1.0-2563eb)
+![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-6b7280)
+
+## What it does
+
+`ucgen` closes the gap between a rough feature idea and a structured use case specification that developers can review and implement. It runs a staged generation pipeline that produces consistent Cockburn-style sections instead of free-form prose. Output is written as Markdown documents with frontmatter plus self-contained HTML reports for review and sharing.
+
+## Quick start
+
+### With Ollama (free, local)
+
+```bash
+pip install ucgen
+ollama pull qwen3:8b
+ucgen generate "warehouse picker scans barcode to confirm item before adding to shipment"
+```
+
+### With Anthropic
+
+```bash
+pip install ucgen
+export ANTHROPIC_API_KEY=sk-ant-...   # Windows: $env:ANTHROPIC_API_KEY=...
+ucgen generate "warehouse picker scans barcode to confirm item before adding to shipment" --provider anthropic --model claude-sonnet-4-6
+```
+
+## Troubleshooting
+
+- **Provider unavailable:** run `ucgen version` to check provider status.
+- **Anthropic auth errors:** confirm `ANTHROPIC_API_KEY` is set in the same shell session.
+- **Ollama connection errors:** start Ollama with `ollama serve` and verify model exists with `ollama list`.
+- **No report output:** ensure generation completed and rerun with `--report`, or run `ucgen report`.
+
+## Output
+
+For the warehouse picker example, `ucgen` creates a per-use-case folder with Markdown, JSON, and optional single-report HTML.
+
+```text
+use-cases/
+  report.html
+  standalone/
+    UC-2026-0049-warehouse-picker-scans-barcode/
+      UC-2026-0049-warehouse-picker-scans-barcode.md
+      UC-2026-0049-warehouse-picker-scans-barcode.json
+      report.html
+```
+
+- `*.md`: human-readable use case document
+- `*.json`: full structured `UseCaseDocument`
+- `report.html`: self-contained HTML report (single-use-case when generated with `--report`)
+
+## Configuration
+
+Initialize local config:
+
+```bash
+ucgen init
+```
+
+Example `.ucgenrc.toml`:
+
+```toml
+[defaults]
+provider = "ollama"
+model = "qwen3:8b"
+output_dir = "./use-cases"
+template = "default"
+temperature = 0.3
+max_tokens = 4000
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ucgen generate "<idea>"` | Generate one use case |
+| `ucgen generate "<idea>" --report` | Generate one use case and a single report in the UC folder |
+| `ucgen batch <ideas.txt>` | Generate from a text/yaml batch file |
+| `ucgen report` | Build portfolio report from all JSON docs in `output_dir` |
+| `ucgen run` | Generate from `ucgen.yaml` project file |
+| `ucgen status` | Show project generation status |
+| `ucgen validate <path>` | Validate generated markdown files |
+| `ucgen init` | Create `.ucgenrc.toml` |
+| `ucgen init-project "<name>"` | Scaffold `ucgen.yaml` |
+| `ucgen log` | Record a mistake in memory |
+| `ucgen gc` | Archive/graduate memory entries |
+| `ucgen version` | Show version and provider availability |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ucgen-0.1.0/core/data-flow.json

@@ -0,0 +1,87 @@
+{
+  "file": "core/data-flow.json",
+  "purpose": "Step-by-step data flow for happy path, all error paths, and YAML project run path",
+
+  "happy_path_single": [
+    {"step": 1, "actor": "cli.py", "action": "Parse CLI args. Load Config. Apply flag overrides. Check ucgen.yaml absent for single mode."},
+    {"step": 2, "actor": "cli.py", "action": "ProviderFactory.create(config) -> provider. Call provider.is_available(). Exit with clear message if False."},
+    {"step": 3, "actor": "cli.py", "action": "asyncio.run(generator.generate(idea, config, provider))"},
+    {"step": 4, "actor": "generator.py", "action": "id_counter.next_id(config.output_dir) -> uc_id"},
+    {"step": 5, "actor": "generator.py", "action": "await _run_intake(idea, uc_id, config, provider) -> IntakeResult"},
+    {"step": 6, "actor": "generator.py", "action": "await _run_sections(intake, config, provider) -> SectionsResult"},
+    {"step": 7, "actor": "generator.py", "action": "await _run_entities(intake, sections, config, provider) -> EntitiesResult"},
+    {"step": 8, "actor": "generator.py", "action": "assembler.assemble(intake, sections, entities, config) -> raw_markdown string"},
+    {"step": 9, "actor": "generator.py", "action": "Return UseCaseDocument with all results + timing"},
+    {"step": 10, "actor": "cli.py", "action": "Write .md file to output_dir. Run on_generate hook if configured."},
+    {"step": 11, "actor": "cli.py", "action": "Print Rich summary: file path, UC ID, provider, model, duration_ms"}
+  ],
+
+  "yaml_project_run_path": [
+    {"step": 1, "actor": "cli.py (run command)", "action": "project_runner.load_project(Path('ucgen.yaml')) -> ProjectDefinition. Fail clearly if PyYAML not installed."},
+    {"step": 2, "actor": "cli.py", "action": "Merge project.defaults into Config. Apply filter_id or filter_tag if passed."},
+    {"step": 3, "actor": "project_runner.py", "action": "Filter use_cases by id/tag/status=pending. Show Rich progress bar."},
+    {"step": 4, "actor": "project_runner.py", "action": "For each use case: asyncio.run(generator.generate(uc.goal, config, provider))"},
+    {"step": 5, "actor": "project_runner.py", "action": "Write file. Update ucgen.yaml use_case status to 'generated'."},
+    {"step": 6, "actor": "cli.py", "action": "Run on_batch_complete hook. Print summary table."}
+  ],
+
+  "yaml_frontmatter_in_output": {
+    "note": "Every generated .md file starts with YAML frontmatter block",
+    "format": "--- ... ---",
+    "fields": ["uc_id", "title", "actor", "goal_level", "domain", "system_boundary", "trigger", "priority", "status", "generator", "provider", "model", "generated_at", "duration_ms", "tags", "stakeholders", "nfr", "scale_hints"],
+    "why": "Machine-readable for ucgen validate, ucgen status, CI tooling, and documentation site generators"
+  },
+
+  "error_paths": {
+    "provider_unavailable": "Exit before pipeline. Rich error panel with diagnostic: is Ollama running? Is API key set?",
+    "stage_parse_failure": "Log WARNING with raw output. Retry once at temp=0.1. On second failure: write raw to .ucgen_debug/. Raise GenerationError.",
+    "entity_stage_failure": "Fallback to minimal entities from intake.related_entities. Log WARNING. Continue to assemble.",
+    "template_render_failure": "Raise AssemblerError — should never happen with valid schema models.",
+    "file_write_failure": "Print generated markdown to stdout as fallback. Log ERROR.",
+    "yaml_project_not_found": "Exit with clear message: 'No ucgen.yaml found. Run ucgen init-project or specify --file.'",
+    "yaml_dep_missing": "Exit with: 'Project files require PyYAML. Run: pip install ucgen[project]'"
+  },
+
+  "data_contracts": {
+    "IntakeResult": {
+      "uc_id": "str — UC-{YYYY}-{NNNN}",
+      "title": "str — proper use case title",
+      "goal_level": "str — summary | user_goal | subfunction",
+      "actor": "str — role, never a person name",
+      "supporting_actors": "list[str] — external systems or roles called by this use case",
+      "stakeholders": "list[dict] — [{name, interest}]",
+      "domain": "str",
+      "system_boundary": "str | None — which service/component owns this",
+      "trigger": "str — specific event",
+      "goal": "str — one sentence",
+      "related_entities": "list[str]",
+      "scale_hints": "dict | None — {frequency, concurrent_users, data_volume}",
+      "raw_input": "str"
+    },
+    "SectionsResult": {
+      "preconditions": "list[str] — 3-6 verifiable states",
+      "minimal_guarantee": "str — what system promises even on failure (Cockburn)",
+      "success_guarantee": "str — what is true for all stakeholders after success",
+      "normal_course": "list[NormalCourseStep]",
+      "alternative_courses": "list[AlternativeCourse]",
+      "postconditions": "list[str]",
+      "information_requirements": "list[InfoRequirement]",
+      "nfr": "list[dict] | None — [{type, requirement, threshold}]",
+      "state_machine": "list[dict] | None — [{state, transitions}] when entity has lifecycle",
+      "open_issues": "list[str] | None — Cockburn open issues field"
+    },
+    "EntitiesResult": {
+      "entities": "list[Entity]"
+    },
+    "UseCaseDocument": {
+      "metadata": "IntakeResult",
+      "sections": "SectionsResult",
+      "entities": "EntitiesResult",
+      "raw_markdown": "str — final assembled document including YAML frontmatter",
+      "generated_at": "datetime UTC",
+      "provider": "str",
+      "model": "str",
+      "duration_ms": "int"
+    }
+  }
+}

ucgen-0.1.0/core/overview.json

@@ -0,0 +1,98 @@
+{
+  "file": "core/overview.json",
+  "purpose": "Design philosophy, pipeline stages, and module map in one file",
+
+  "design_philosophy": {
+    "principles": [
+      "Each generation stage is a separate focused LLM call — never one giant prompt",
+      "Providers are fully interchangeable — same BaseProvider interface, different backends",
+      "Prompts are external .md files loaded at runtime — never inline Python strings",
+      "Templates are Jinja2 .j2 files — never f-strings for document assembly",
+      "Assembler stage is pure Python — no LLM in final document construction",
+      "All LLM calls are async — asyncio.run() called exactly once in cli.py",
+      "Fail loud: never write a partial document, always surface errors with full context",
+      "Three extension seams only: BaseProvider, Jinja2 templates, lifecycle hooks"
+    ]
+  },
+
+  "pipeline_stages": [
+    {
+      "id": 1,
+      "name": "intake",
+      "input": "raw string from user",
+      "output_type": "IntakeResult",
+      "prompt_file": "ucgen/prompts/stage1_intake.md",
+      "llm_required": true,
+      "retry": {"max": 1, "temperature": 0.1},
+      "on_failure": "raise IntakeParseError with raw_output attached"
+    },
+    {
+      "id": 2,
+      "name": "sections",
+      "input": "IntakeResult",
+      "output_type": "SectionsResult",
+      "prompt_file": "ucgen/prompts/stage2_sections.md",
+      "llm_required": true,
+      "retry": {"max": 1, "temperature": 0.1},
+      "on_failure": "raise SectionsParseError"
+    },
+    {
+      "id": 3,
+      "name": "entities",
+      "input": "IntakeResult + SectionsResult",
+      "output_type": "EntitiesResult",
+      "prompt_file": "ucgen/prompts/stage3_entities.md",
+      "llm_required": true,
+      "retry": {"max": 1, "temperature": 0.1},
+      "on_failure": "fallback to minimal entities from IntakeResult.related_entities — log WARNING, do not raise"
+    },
+    {
+      "id": 4,
+      "name": "assemble",
+      "input": "IntakeResult + SectionsResult + EntitiesResult + Config",
+      "output_type": "UseCaseDocument",
+      "prompt_file": null,
+      "llm_required": false,
+      "on_failure": "raise AssemblerError — should never happen with valid inputs"
+    }
+  ],
+
+  "module_map": {
+    "ucgen/__init__.py": "Package version export only. __version__ = '0.1.0'",
+    "ucgen/cli.py": "Typer CLI. All commands. Zero business logic — delegates entirely.",
+    "ucgen/generator.py": "Orchestrates 4-stage pipeline. Only module that calls providers.",
+    "ucgen/assembler.py": "Pure Python Jinja2 renderer. No LLM. Takes all stage results, returns markdown string.",
+    "ucgen/schema.py": "All Pydantic v2 models. Single source of truth for data shapes.",
+    "ucgen/config.py": "Loads .ucgenrc.toml project then home. Returns typed Config object.",
+    "ucgen/project_runner.py": "Reads ucgen.yaml, orchestrates multi-use-case runs. Tier 2 feature.",
+    "ucgen/validator.py": "Validates existing .md use case files against ucgen schema.",
+    "ucgen/exporter.py": "Converts UseCaseDocument to JSON or YAML string.",
+    "ucgen/errors.py": "All custom exception classes. Single file.",
+    "ucgen/providers/__init__.py": "Exports ProviderFactory only.",
+    "ucgen/providers/base.py": "Abstract BaseProvider + GenerationResult dataclass.",
+    "ucgen/providers/ollama.py": "OllamaProvider — async httpx to local Ollama REST API.",
+    "ucgen/providers/anthropic_provider.py": "AnthropicProvider — official anthropic SDK via asyncio.to_thread.",
+    "ucgen/providers/openai_provider.py": "OpenAICompatibleProvider — openai AsyncClient. Covers OpenAI, Groq, Together, LM Studio.",
+    "ucgen/providers/factory.py": "ProviderFactory.create(config) -> BaseProvider.",
+    "ucgen/utils/json_extract.py": "extract_json(raw) — robustly extracts JSON from LLM output with commentary.",
+    "ucgen/utils/id_counter.py": "next_id(output_dir) — reads/increments .ucgen_counter file.",
+    "ucgen/utils/table_formatter.py": "format_table(raw) — normalizes markdown table column widths.",
+    "ucgen/utils/prompt_loader.py": "load_prompt(name) — loads and caches prompt .md files.",
+    "ucgen/prompts/system_base.md": "Shared persona injected into every stage system prompt.",
+    "ucgen/prompts/stage1_intake.md": "Stage 1 prompt content.",
+    "ucgen/prompts/stage2_sections.md": "Stage 2 prompt content.",
+    "ucgen/prompts/stage3_entities.md": "Stage 3 prompt content.",
+    "ucgen/templates/default.md.j2": "Standard full use case template.",
+    "ucgen/templates/minimal.md.j2": "Quick capture template.",
+    "ucgen/templates/api.md.j2": "API-focused use case template.",
+    "ucgen/templates/cockburn-full.md.j2": "Full Cockburn format with all fields.",
+    "ucgen/templates/enterprise.md.j2": "Enterprise format with NFRs, scale hints, state machine."
+  },
+
+  "provider_quality_tiers": [
+    {"provider": "ollama", "models": ["mistral", "qwen2.5:14b"], "quality": "Good", "cost": "Free", "recommended_for": "Tier 1 offline"},
+    {"provider": "groq", "models": ["llama-3.3-70b-versatile"], "quality": "Excellent", "cost": "Free tier generous", "recommended_for": "Tier 1/2 free cloud"},
+    {"provider": "anthropic", "models": ["claude-sonnet-4-6", "claude-haiku-4-5-20251001"], "quality": "Best consistency", "cost": "~$0.003/doc", "recommended_for": "Tier 2/3 production"},
+    {"provider": "openai", "models": ["gpt-4o-mini", "gpt-4o"], "quality": "Excellent", "cost": "~$0.001/doc", "recommended_for": "Tier 2/3 production"}
+  ]
+}

ucgen-0.1.0/ideas-10.txt

@@ -0,0 +1,10 @@
+customer pays for order at checkout using saved card
+warehouse picker receives batch orders on handheld device and scans items
+AI agent monitors competitor websites every 6 hours and alerts sales team via Slack when price drops exceed 10 percent
+Danish farmer submits EU crop rotation subsidy claim with field maps and crop types
+startup founder upgrades team from free plan to Pro and system processes prorated Stripe payment
+property buyer makes offer on listing and system tracks counter-offers with version history
+patient with chronic condition books follow-up with specialist after insurance verification
+driver picks up parcel from warehouse and marks items as collected on mobile device
+user invites new team member to workspace and system sends onboarding email with role permissions
+system sends automated low stock alert to procurement team when inventory drops below threshold