ai/chat.py - ChatSession

Purpose: Manages the complete chat lifecycle: input validation → sanitization → context retrieval → AI call → output filtering → history storage.

Flow of send(message):

1. AIGuardrails.validate_input(message) - Block injection/forbidden topics
2. LeakPrevention.sanitize_for_ai(message) - Strip sensitive data
3. get_context(sanitized) - RAG query for relevant code chunks
4. get_error_context() - Format detected errors as context
5. provider.chat(sanitized, full_context) - Send to AI with combined context
6. AIGuardrails.validate_output(response) - Filter leaks from AI response
7. Append both messages to self.history

Context format: Each RAG chunk becomes "file_path:start_line-end_line\n{code_content}". Errors become "- file:line [severity] message".

ai/system_prompt.py

Purpose: Hardcoded system prompt with 10 strict behavioral rules for the AI.

Rules: Code-only topics, no command execution, no prompt leakage, no personal opinions, no harmful code, always explain reasoning, ask for clarification when needed, format code properly, no speculation about users, stay in character as Loki.

providers/base.py - AIProvider (ABC)

Purpose: Abstract base class defining the interface all AI providers must implement.

Abstract methods: chat(prompt, context) -> str, embed(text) -> list[float], validate_key(key) -> bool

providers/groq.py - GroqProvider

Purpose: Default free AI provider. Uses Groq's fast inference API.

Implementation: groq.Groq(api_key=key).chat.completions.create(model=model, messages=[{system}, {user}])

Key validation: Regex r'^gsk_[a-zA-Z0-9]{48}$'

Default model: llama-3.3-70b-versatile

System prompt: Built from system_prompt.py with additional codebase context injected.

providers/openai_provider.py - OpenAIProvider

Purpose: OpenAI API integration (optional dependency).

Implementation: openai.OpenAI(api_key=key).chat.completions.create(model=model, messages=[...])

Also supports: embeddings.create() for vector embeddings.

Key validation: Regex r'^sk-[a-zA-Z0-9]{48}$'

providers/anthropic.py - AnthropicProvider

Purpose: Anthropic Claude API integration (optional dependency).

Implementation: anthropic.Anthropic(api_key=key).messages.create(model=model, max_tokens=4096, system=system, messages=[...])

Key validation: Regex r'^sk-ant-[a-zA-Z0-9]{93}$'

providers/openrouter.py - OpenRouterProvider

Purpose: OpenRouter API integration - access to multiple models via HTTP.

Implementation: Raw HTTP POST to https://openrouter.ai/api/v1/chat/completions using httpx.

Key validation: Regex r'^sk-or-[a-zA-Z0-9]{64}$'

ai/rag.py - RAGEngine

Purpose: Builds a vector search index over your codebase so the AI can find and understand relevant code when answering questions.

How it works:

1. Chunking: chunk_code() splits each file into 50-line chunks with 10-line overlap. Each chunk becomes a CodeChunk(file_path, start_line, end_line, content, language)
2. Embedding: SentenceTransformer("all-MiniLM-L6-v2") converts each chunk's text into a 384-dimensional vector
3. Indexing: faiss.IndexFlatL2(384) stores all vectors. L2 distance for similarity search.
4. Saving: faiss.write_index() saves the index. chunks.json stores chunk metadata.
5. Querying: User question → embed → index.search(embedding, top_k=5) → return 5 most relevant chunks

Libraries:

• faiss-cpu - Facebook's vector similarity search library
• sentence-transformers - Hugging Face model for text embeddings
• numpy - Array operations for FAISS

Storage: ~/.loki/{project_hash}/embeddings/index.faiss + chunks.json

Current state: 124 chunks indexed, 190KB index file, 162KB chunks.json

ui/server.py - UIServer

Purpose: FastAPI web server that serves the web UI and API endpoints.

Features:

• CORS configured for localhost only (127.0.0.1:8080)
• Serves static files from ui/static/
• Auto-opens browser on start with webbrowser.open()
• Uses uvicorn.run() for ASGI server

ui/routes.py - API Endpoints

Endpoints:

• GET /api/files - Returns file tree with error counts per file
• GET /api/errors?file= - Returns errors, optionally filtered by file path
• GET /api/content?file= - Returns raw file content for code viewer
• POST /api/chat - Sends message to AI, returns response with RAG context
• WS /ws/chat - WebSocket for real-time chat
• GET /api/runtime-errors - Returns captured runtime errors

Key pattern: All functions handle both dict and dataclass objects from cache using _get_attr() helper.

ui/security.py - Rate Limiter & Sanitizer

Functions:

• RateLimiter.is_allowed(ip) - In-memory per-IP rate limiting (prevents abuse)
• InputSanitizer.sanitize_file_path(path) - Prevents directory traversal (removes ../, ..\\)
• InputSanitizer.sanitize_message(msg) - HTML escapes, limits length to 1000 chars, removes control characters

ui/static/index.html

Purpose: Single-page application with three-panel layout.

Layout:

• Left panel (280px): File tree sidebar + stats (files, errors, warnings)
• Center panel (1fr): Code viewer with Prism.js syntax highlighting + error list
• Right panel (360px): AI chat sidebar

External libraries (CDN):

• Three.js r128: Animated neural-graph background with 95 particles and dynamic links
• Prism.js 1.29.0: Syntax highlighting for code blocks
• Google Fonts: Space Grotesk (headings), Inter (body), JetBrains Mono (code)

Mobile support: Slide-over drawers with hamburger menu at 900px breakpoint

ui/static/style.css

Purpose: Complete dark-theme CSS with "developer HUD" aesthetic.

Key features:

• 30+ CSS custom properties for theming
• Glass-panel effects with backdrop-filter: blur
• Neon cyan (#00f0ff) and violet (#b84dff) accent colors
• Animated corner brackets (corner-breathe animation)
• Scan-sweep gradient animation on active elements
• Holographic tilt effects on hover
• Custom scrollbar styling
• Responsive breakpoints: 1180px, 900px, 600px

ui/static/app.js

Purpose: Frontend JavaScript - fetches data from API, renders UI, handles chat.

Key functions:

• loadFiles() - Fetches /api/files, renders file tree with icons and error badges
• loadContent(filePath, ext) - Fetches /api/content, applies Prism.js highlighting
• loadAllErrors() - Fetches /api/errors, updates stats and error list
• sendChat() - POST to /api/chat, appends response to chat panel
• getLanguageClass(ext) - Maps file extensions to Prism.js language classes
• escapeHtml(text) - Prevents XSS via DOM textContent
• Prism.highlightElement(codeElement) - Applies syntax highlighting to code blocks

.github/workflows/test.yml

Purpose: Runs tests and linting on every push/PR to main.

Steps: Checkout → Setup Python (3.10/3.11/3.12 matrix) → Install deps → pytest tests/ -v --cov=loki → ruff check .

.github/workflows/publish.yml

Purpose: Auto-publishes to PyPI when a GitHub release is created.

Steps: Checkout → Setup Python → Build (python -m build) → Publish (pypa/gh-action-pypi-publish@release/v1 with trusted publishing)

tests/test_cache.py

Tests: test_cache_save_and_load() - Creates temp directory, saves ScanResult, loads it back, verifies data matches. test_cache_exists() - Verifies exists() returns False when no cache, True after save.

tests/test_commands.py

Tests: test_init_creates_cache() - Creates temp project with a Python file, runs execute_init(), verifies cache directory exists.

tests/test_errors.py

Tests: test_detect_syntax_errors() - Creates file with syntax error (unclosed bracket), runs ErrorDetector, verifies error is found. Creates valid file, verifies no errors.

tests/test_providers.py

Tests: test_groq_validate_key() - Verifies valid gsk_ key is accepted, invalid keys rejected.

tests/test_scanner.py

Tests: test_scanner_finds_python_files() - Creates temp dir with .py file, runs scanner, verifies file is found. test_scanner_respects_ignore_patterns() - Creates __pycache__ directory, verifies it's skipped.

tests/test_security.py

Tests: test_sanitize_api_key() - Passes text with API key, verifies it's redacted to [REDACTED]. test_sanitize_for_ai() - Verifies os.environ calls are stripped.