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.