diff --git a/todo/IMPLEMENTATION_ISSUES.md b/todo/IMPLEMENTATION_ISSUES.md new file mode 100644 index 00000000..3adad0e8 --- /dev/null +++ b/todo/IMPLEMENTATION_ISSUES.md @@ -0,0 +1,386 @@ +# 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 ` +- [ ] 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