markitect-main/history/IMPLEMENTATION_ISSUES.md

# LLM Integration Implementation Issues

**Generated**: 2025-10-03
**Source**: LLM_INTEGRATION_GAMEPLAN.md
**Target Features**: Issue #98 (OpenRoute Integration) & Issue #99 (Auto Fill Templates)

This document contains 10 specific GitHub issues ready for implementation, broken down from the comprehensive gameplan into actionable development tasks.

## Priority Matrix

| Priority | Issue Count | Description |
|----------|-------------|-------------|
| **High** | 4 issues | Core infrastructure and foundational components |
| **Medium** | 4 issues | User-facing features and integration |
| **Low** | 2 issues | Advanced capabilities and polish |

## Dependency Chain

```
Foundation Layer:
├── Issue 1: OpenRouter Client ← (no dependencies)
├── Issue 2: Config Extensions ← depends on Issue 1
├── Issue 6: Template Field Analysis ← (no dependencies)
└── Issue 8: Profile Management ← (no dependencies)

Integration Layer:
├── Issue 3: Context Builder ← depends on Issue 1
├── Issue 4: Natural Language Enhancement ← depends on Issues 1, 3
├── Issue 5: Basic LLM CLI ← depends on Issues 1, 2
└── Issue 7: Interactive Questionnaire ← depends on Issue 6

Advanced Layer:
├── Issue 9: LLM Auto-Fill ← depends on Issues 1, 6, 8
└── Issue 10: Advanced Fill Commands ← depends on Issues 7, 9
```

---

## Issue 1: Implement OpenRouter LLM Client Infrastructure

**Priority**: HIGH | **Effort**: 2 days | **Dependencies**: None

### User Story
As a developer, I want a robust OpenRouter client so that MarkiTect can connect to and interact with various LLM models through the OpenRouter API.

### Description
Create the foundational OpenRouter client infrastructure that will enable all LLM-powered features in MarkiTect. This includes API communication, model management, rate limiting, and error handling.

### Technical Implementation
- **New Files**:
  - `markitect/llm/__init__.py`
  - `markitect/llm/openrouter_client.py`
  - `markitect/llm/exceptions.py`
  - `tests/test_openrouter_client.py`
- **Modified Files**:
  - `requirements.txt` (add httpx, pydantic)
  - `markitect/config_manager.py` (add OpenRouter config keys)
- **Dependencies**: None

### Acceptance Criteria
- [ ] OpenRouterClient class with async API communication
- [ ] Support for multiple models (GPT-4, Claude, etc.)
- [ ] Rate limiting and retry logic with exponential backoff
- [ ] Comprehensive error handling for API failures
- [ ] Token usage tracking and cost estimation
- [ ] Unit tests with >90% coverage
- [ ] Integration tests with mock API responses
- [ ] Documentation with usage examples

---

## Issue 2: Extend Configuration System for LLM Integration

**Priority**: HIGH | **Effort**: 1 day | **Dependencies**: Issue 1

### User Story
As a user, I want to configure my OpenRouter API credentials and LLM preferences through MarkiTect's configuration system so that I can seamlessly use AI features.

### Description
Extend the existing configuration management system to support OpenRouter API keys, model preferences, and LLM-related settings with proper validation and secure storage.

### Technical Implementation
- **New Files**: None
- **Modified Files**:
  - `markitect/config_manager.py`
  - `tests/test_issue_18_config_management.py`
- **Dependencies**: Issue 1

### Acceptance Criteria
- [ ] Add openrouter.api_key, openrouter.default_model config keys
- [ ] Implement sensitive data masking for API keys
- [ ] Add validation for OpenRouter API key format
- [ ] Support for model-specific settings (temperature, max_tokens)
- [ ] CLI commands: `markitect config-set openrouter.api_key <key>`
- [ ] CLI command: `markitect config-show --show-sensitive`
- [ ] Configuration file format documentation
- [ ] Tests for new configuration functionality

---

## Issue 3: Create LLM Content Context Builder

**Priority**: HIGH | **Effort**: 3 days | **Dependencies**: Issue 1

### User Story
As a user, I want the LLM to have relevant context from my MarkiTect content when answering questions so that responses are accurate and cite my actual documents.

### Description
Build a smart context builder that extracts relevant content from the MarkiTect database, uses FTS search for content discovery, and constructs context within token limits while maintaining source citations.

### Technical Implementation
- **New Files**:
  - `markitect/llm/context_builder.py`
  - `markitect/llm/content_selector.py`
  - `tests/test_context_builder.py`
- **Modified Files**: None
- **Dependencies**: Issue 1

### Acceptance Criteria
- [ ] ContextBuilder class with intelligent content selection
- [ ] Integration with existing FTS search capabilities
- [ ] Token-aware context truncation and optimization
- [ ] Source tracking and citation generation
- [ ] Relevance scoring for content ranking
- [ ] Support for different context strategies (recent, relevant, comprehensive)
- [ ] Performance optimization for large content repositories
- [ ] Unit tests with mock database content

---

## Issue 4: Enhance Natural Language Paradigm with Real LLM Integration

**Priority**: MEDIUM | **Effort**: 2 days | **Dependencies**: Issues 1, 3

### User Story
As a user, I want to ask natural language questions about my content and receive intelligent, contextual responses from actual LLMs rather than mock responses.

### Description
Upgrade the existing Natural Language Query Paradigm to use real OpenRouter LLM integration, replacing the current translation-based approach with context-aware LLM processing.

### Technical Implementation
- **New Files**: None
- **Modified Files**:
  - `markitect/query_paradigms/paradigms/natural_language_paradigm.py`
  - `tests/test_natural_language_paradigm.py`
- **Dependencies**: Issues 1, 3

### Acceptance Criteria
- [ ] Replace query translation with direct LLM processing
- [ ] Context injection from MarkiTect content
- [ ] Source citations in LLM responses
- [ ] Support for follow-up questions and conversations
- [ ] Response formatting with markdown support
- [ ] Error handling for LLM API failures
- [ ] Integration with existing paradigm registry
- [ ] Comprehensive tests with mock LLM responses

---

## Issue 5: Add Basic LLM CLI Commands

**Priority**: MEDIUM | **Effort**: 1 day | **Dependencies**: Issues 1, 2

### User Story
As a user, I want basic CLI commands to test my OpenRouter connection and perform simple LLM interactions so that I can verify my setup and explore AI capabilities.

### Description
Implement fundamental CLI commands for LLM interaction, including connection testing, model listing, and basic query execution with MarkiTect context.

### Technical Implementation
- **New Files**:
  - `markitect/llm/commands.py`
  - `tests/test_llm_commands.py`
- **Modified Files**:
  - `markitect/cli.py`
- **Dependencies**: Issues 1, 2

### Acceptance Criteria
- [ ] Command: `markitect llm test` - Test OpenRouter connection
- [ ] Command: `markitect llm models` - List available models
- [ ] Command: `markitect llm ask "question"` - Basic LLM query
- [ ] Command: `markitect llm chat` - Interactive chat mode
- [ ] Proper error handling and user feedback
- [ ] Integration with existing Click CLI framework
- [ ] Support for configuration options and flags
- [ ] CLI help documentation and examples

---

## Issue 6: Implement Template Field Analysis and Parsing

**Priority**: HIGH | **Effort**: 3 days | **Dependencies**: None

### User Story
As a template creator, I want enhanced template parsing that can identify field types, descriptions, and validation rules so that the system can intelligently handle template completion.

### Description
Extend the existing template system to parse advanced field annotations, extract metadata, and support various input types for the interactive questionnaire system.

### Technical Implementation
- **New Files**:
  - `markitect/template/field_analyzer.py`
  - `markitect/template/field_types.py`
  - `tests/test_template_field_analyzer.py`
- **Modified Files**:
  - `markitect/template/parser.py`
- **Dependencies**: None

### Acceptance Criteria
- [ ] Parse template annotations: `{{name:string:Your full name}}`
- [ ] Support field types: text, choice, date, number, boolean, email
- [ ] Extract field descriptions and validation rules
- [ ] Identify required vs optional fields
- [ ] Support nested field structures and conditional logic
- [ ] Backward compatibility with existing templates
- [ ] Field validation and constraint checking
- [ ] Comprehensive tests with various template formats

---

## Issue 7: Create Interactive Template Questionnaire System

**Priority**: MEDIUM | **Effort**: 4 days | **Dependencies**: Issue 6

### User Story
As a user, I want to fill templates through an interactive terminal questionnaire that guides me through each field with appropriate input validation and user-friendly prompts.

### Description
Build a terminal-based interactive questionnaire engine that presents template fields to users, handles different input types, validates responses, and provides a smooth completion experience.

### Technical Implementation
- **New Files**:
  - `markitect/template/questionnaire.py`
  - `markitect/template/input_handlers.py`
  - `tests/test_template_questionnaire.py`
- **Modified Files**: None
- **Dependencies**: Issue 6

### Acceptance Criteria
- [ ] Interactive terminal interface with clear prompts
- [ ] Support for all field types (text, choice, date, number, boolean)
- [ ] Input validation with re-prompting on errors
- [ ] Progress tracking and partial save capability
- [ ] Skip/default options for optional fields
- [ ] Colorful and user-friendly terminal output
- [ ] Keyboard shortcuts and navigation
- [ ] Tests with simulated user input

---

## Issue 8: Implement User Profile Management System

**Priority**: HIGH | **Effort**: 2 days | **Dependencies**: None

### User Story
As a user, I want to create and manage multiple profiles containing my personal and professional information so that templates can be auto-filled with my preferred data.

### Description
Create a comprehensive user profile management system with CRUD operations, multiple profile support, and integration with the database for persistent storage.

### Technical Implementation
- **New Files**:
  - `markitect/profile/__init__.py`
  - `markitect/profile/manager.py`
  - `markitect/profile/schema.py`
  - `markitect/profile/commands.py`
  - `tests/test_profile_manager.py`
- **Modified Files**:
  - `markitect/cli.py`
  - Database schema (migration script needed)
- **Dependencies**: None

### Acceptance Criteria
- [ ] Profile CRUD operations (create, read, update, delete)
- [ ] Support for multiple named profiles (personal, work, etc.)
- [ ] JSON Schema validation for profile data
- [ ] Database integration with user_profiles table
- [ ] CLI commands: `markitect profile create/show/set/list/export`
- [ ] Profile inheritance and template support
- [ ] Data export/import functionality
- [ ] Comprehensive tests for all profile operations

---

## Issue 9: Develop LLM-Powered Template Auto-Fill System

**Priority**: MEDIUM | **Effort**: 4 days | **Dependencies**: Issues 1, 6, 8

### User Story
As a user, I want templates to be automatically filled with appropriate values based on my profile and the template context using AI assistance so that I can complete forms quickly and accurately.

### Description
Create an intelligent auto-fill system that uses OpenRouter LLMs to suggest field values based on user profiles, template context, and learned preferences.

### Technical Implementation
- **New Files**:
  - `markitect/template/auto_filler.py`
  - `markitect/template/smart_suggestions.py`
  - `tests/test_template_auto_filler.py`
- **Modified Files**: None
- **Dependencies**: Issues 1, 6, 8

### Acceptance Criteria
- [ ] LLMAutoFiller class with context-aware suggestions
- [ ] Integration with user profile data for personalization
- [ ] Smart field completion based on template purpose
- [ ] Learning from user corrections and preferences
- [ ] Support for complex field generation (descriptions, summaries)
- [ ] Confidence scoring for suggestions
- [ ] Fallback mechanisms when LLM is unavailable
- [ ] Tests with mock LLM responses and profiles

---

## Issue 10: Integrate Advanced Template Fill Commands

**Priority**: LOW | **Effort**: 2 days | **Dependencies**: Issues 7, 9

### User Story
As a user, I want advanced template filling commands that combine interactive questionnaires with AI auto-fill so that I can choose the most appropriate completion method for each situation.

### Description
Create comprehensive CLI commands that integrate all template filling capabilities, offering multiple modes (auto, interactive, guided) and advanced options for different use cases.

### Technical Implementation
- **New Files**:
  - `markitect/template/fill_commands.py`
  - `tests/test_template_fill_commands.py`
- **Modified Files**:
  - `markitect/cli.py`
- **Dependencies**: Issues 7, 9

### Acceptance Criteria
- [ ] Command: `markitect template-fill <template> --auto` - Full auto-fill
- [ ] Command: `markitect template-fill <template> --guided` - Mixed auto + questions
- [ ] Command: `markitect template-fill <template> --interactive` - Pure questionnaire
- [ ] Command: `markitect template-fill <template> --profile=<name>` - Use specific profile
- [ ] Support for output to file or stdout
- [ ] Learning mode that improves suggestions over time
- [ ] Comprehensive error handling and user feedback
- [ ] Integration tests with real templates and profiles

---

## Implementation Recommendations

### Phase 1: Foundation (High Priority Issues - 8 days total)
1. **Issue 1**: OpenRouter Client (2 days)
2. **Issue 6**: Template Field Analysis (3 days)
3. **Issue 8**: Profile Management (2 days)
4. **Issue 2**: Config Extensions (1 day)

**Value Delivered**: Core infrastructure ready for LLM integration and template enhancements

### Phase 2: Integration (Medium Priority Issues - 7 days total)
5. **Issue 3**: Context Builder (3 days)
6. **Issue 4**: Natural Language Enhancement (2 days)
7. **Issue 5**: Basic LLM CLI (1 day)
8. **Issue 7**: Interactive Questionnaire (4 days) - can start after Issue 6

**Value Delivered**: Working LLM queries and interactive template filling

### Phase 3: Advanced Features (Low Priority Issues - 6 days total)
9. **Issue 9**: LLM Auto-Fill (4 days)
10. **Issue 10**: Advanced Fill Commands (2 days)

**Value Delivered**: AI-powered template completion and advanced user experience

### Total Estimated Effort: 21 development days (4-5 weeks with testing and integration)

## Quality Assurance Notes

- Each issue includes comprehensive testing requirements
- Integration points are clearly defined to prevent conflicts
- Backward compatibility is maintained throughout
- Error handling and fallback mechanisms are prioritized
- Performance considerations are included for large repositories

## Risk Mitigation

- **External API Dependency**: All LLM features include fallback modes
- **Configuration Complexity**: Setup wizards and clear documentation planned
- **User Experience**: Iterative testing and feedback incorporation
- **Performance**: Benchmark requirements specified for each component

This implementation plan transforms the strategic gameplan into actionable development work with clear priorities, dependencies, and success criteria.