# Implementation Plan: MOSAICX Python Package for Radiology Report Extraction

**Branch**: `001-python-package-mosaicx` | **Date**: September 11, 2025 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-python-package-mosaicx/spec.md`

## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Evaluate Constitution Check section below
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
4. Execute Phase 0 → research.md
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
6. Re-evaluate Constitution Check section
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
8. STOP - Ready for /tasks command
```

**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)

## Summary
MOSAICX is an intelligent Python package for radiology report extraction that uses local LLMs (Ollama + OpenAI + DSPy) to extract structured data, summaries, or insights from PDF and text radiology reports. The system provides both an intuitive CLI tool and a Python library with smart defaults, interactive schema building, and multi-report patient history analysis capabilities.

## Technical Context
**Language/Version**: Python 3.11+  
**Primary Dependencies**: Ollama, OpenAI API wrapper, DSPy, Rich (terminal UI), PyPDF2/pdfplumber (PDF processing), Click (CLI), Pydantic (data validation)  
**Storage**: File-based (JSON/CSV outputs), optional schema caching  
**Testing**: pytest, pytest-asyncio  
**Target Platform**: Cross-platform (macOS, Linux, Windows)
**Project Type**: Single project (Python package with CLI)  
**Performance Goals**: <5s single report processing, <30s batch processing (10 reports), <2GB memory usage  
**Constraints**: Local-only LLM processing (no external API calls), offline capable after initial setup  
**Scale/Scope**: Handle 1-1000 reports per batch, support PDF files up to 50MB, 10-100 concurrent schema definitions

## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

**Simplicity**:
- Projects: 1 (Python package with CLI interface)
- Using framework directly? Yes (Click for CLI, Rich for terminal UI, direct LLM APIs)
- Single data model? Yes (unified extraction model with optional schema variations)
- Avoiding patterns? Yes (no unnecessary abstractions, direct LLM integration)

**Architecture**:
- EVERY feature as library? Yes (core extraction engine as library, CLI as thin wrapper)
- Libraries listed: 
  - mosaicx.core (extraction engine)
  - mosaicx.cli (command-line interface)
  - mosaicx.schemas (schema management)
  - mosaicx.extractors (LLM processing)
- CLI per library: Single `mosaicx` command with subcommands (extract, schema, analyze)
- Library docs: Yes, llms.txt format with examples and docstrings

**Testing (NON-NEGOTIABLE)**:
- RED-GREEN-Refactor cycle enforced? Yes (tests written before implementation)
- Git commits show tests before implementation? Yes (test files committed first)
- Order: Contract→Integration→E2E→Unit strictly followed? Yes
- Real dependencies used? Yes (actual Ollama instances, real PDF files for testing)
- Integration tests for: LLM integration, PDF processing, schema validation, CLI commands
- FORBIDDEN: Implementation before test, skipping RED phase

**Observability**:
- Structured logging included? Yes (audit logs, processing logs, error tracking)
- Frontend logs → backend? N/A (single application)
- Error context sufficient? Yes (detailed error messages with suggestions)

**Versioning**:
- Version number assigned? 0.1.0 (initial development version)
- BUILD increments on every change? Yes (semantic versioning)
- Breaking changes handled? Yes (schema versioning, migration support)

## Project Structure

### Documentation (this feature)
```
specs/001-python-package-mosaicx/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
├── contracts/           # Phase 1 output (/plan command)
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
```

### Source Code (repository root)
```
mosaicx/
├── __init__.py
├── core/
│   ├── __init__.py
│   ├── extractor.py     # Main extraction engine
│   ├── llm_processor.py # LLM integration (Ollama + DSPy)
│   └── report_parser.py # PDF/text parsing
├── schemas/
│   ├── __init__.py
│   ├── builder.py       # Interactive schema builder
│   ├── templates.py     # Built-in schema templates
│   └── validator.py     # Schema validation
├── cli/
│   ├── __init__.py
│   ├── main.py         # CLI entry point
│   ├── extract.py      # Extract command
│   └── schema.py       # Schema management commands
├── utils/
│   ├── __init__.py
│   ├── logging.py      # Audit and process logging
│   ├── progress.py     # Terminal progress displays
│   └── validation.py   # Data validation utilities
└── extractors/
    ├── __init__.py
    ├── single_report.py    # Single report processing
    ├── multi_report.py     # Patient history analysis
    └── summarizer.py       # Summary generation

tests/
├── contract/           # API contract tests
├── integration/        # LLM and file processing tests
├── e2e/               # End-to-end CLI tests
└── unit/              # Unit tests for individual modules

docs/                  # Auto-generated documentation
examples/              # Example reports and schemas
schemas/               # Built-in schema templates
```

## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
   - For each NEEDS CLARIFICATION → research task
   - For each dependency → best practices task
   - For each integration → patterns task

2. **Generate and dispatch research agents**:
   ```
   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   ```

3. **Consolidate findings** in `research.md` using format:
   - Decision: [what was chosen]
   - Rationale: [why chosen]
   - Alternatives considered: [what else evaluated]

**Output**: research.md with all NEEDS CLARIFICATION resolved

## Phase 1: Design & Contracts
*Prerequisites: research.md complete*

1. **Extract entities from feature spec** → `data-model.md`:
   - Entity name, fields, relationships
   - Validation rules from requirements
   - State transitions if applicable

2. **Generate API contracts** from functional requirements:
   - For each user action → endpoint
   - Use standard REST/GraphQL patterns
   - Output OpenAPI/GraphQL schema to `/contracts/`

3. **Generate contract tests** from contracts:
   - One test file per endpoint
   - Assert request/response schemas
   - Tests must fail (no implementation yet)

4. **Extract test scenarios** from user stories:
   - Each story → integration test scenario
   - Quickstart test = story validation steps

5. **Update agent file incrementally** (O(1) operation):
   - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
   - If exists: Add only NEW tech from current plan
   - Preserve manual additions between markers
   - Update recent changes (keep last 3)
   - Keep under 150 lines for token efficiency
   - Output to repository root

**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file

## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*

**Task Generation Strategy**:
- Load `/templates/tasks-template.md` as base
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
- Each contract → contract test task [P]
- Each entity → model creation task [P] 
- Each user story → integration test task
- Implementation tasks to make tests pass

**Ordering Strategy**:
- TDD order: Tests before implementation 
- Dependency order: Models before services before UI
- Mark [P] for parallel execution (independent files)

**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md

**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan

## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*

**Phase 3**: Task execution (/tasks command creates tasks.md)  
**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)

## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |


## Progress Tracking
*This checklist is updated during execution flow*

**Phase Status**:
- [ ] Phase 0: Research complete (/plan command)
- [ ] Phase 1: Design complete (/plan command)
- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed

**Gate Status**:
- [ ] Initial Constitution Check: PASS
- [ ] Post-Design Constitution Check: PASS
- [ ] All NEEDS CLARIFICATION resolved
- [ ] Complexity deviations documented

---
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*