{
  "markdown": "# Karakana Local Context Engine 🤖📚\n\n**Multi-Provider RAG System** — Ingest engineering docs and code into a queryable knowledge base served via Chainlit chat UI. Supports three inference backends: Local (Ollama), NVIDIA API, and OpenAI Cloud.\n\n---\n\n## 🎯 What This Does\n\n1. **Ingest**: Scans `./docs` for `.md` and `.py` files\n2. **Generate Q&A**: Two-pass LLM pipeline creates question-answer pairs:\n   - Pass 1 (Macro): 3 high-level architectural Q&A per file\n   - Pass 2 (Micro): 2 detailed code-level Q&A per 1500-char chunk\n3. **Index**: Embeds Q&A pairs into ChromaDB vector store\n4. **Serve**: Chainlit chat UI at `http://localhost:3000` with streaming responses and source citations\n\n---\n\n## 🏗️ Architecture\n\n```\ndocs/*.md, *.py\n       │\n       ▼\n┌─────────────────────────────────────┐\n│  Dual-Pass Q&A Generation           │\n│  (configurable model provider)      │\n└─────────────────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────────┐\n│  ChromaDB Vector Store              │\n│  (persistent .chroma/)              │\n└─────────────────────────────────────┘\n       │\n       ▼\n┌─────────────────────────────────────┐\n│  Chainlit Chat UI (port 3000)       │\n│  RAG: Retriever → Prompt → LLM      │\n│  Streaming + Source Citations       │\n└─────────────────────────────────────┘\n```\n\n---\n\n## 🚀 Quick Start\n\n### 1. Install Dependencies\n```bash\nmake setup\n```\n\n### 2. Choose Your Provider\n\n| Provider | Command | Requirements |\n|----------|---------|--------------|\n| **Local (Ollama)** | `make run-local` | `ollama serve` + `ollama pull mistral-nemo:12b nomic-embed-text` |\n| **NVIDIA API** | `make run-nvidia` | `export NVIDIA_API_KEY=...` |\n| **OpenAI Cloud** | `make run-cloud` | `export OPENAI_API_KEY=...` |\n\n### 3. Generate Knowledge Base\n```bash\n# First run auto-generates, or run explicitly:\nmake generate\n```\n\n### 4. Chat\nOpen `http://localhost:3000` and ask questions about your codebase.\n\n---\n\n## ⚙️ Configuration\n\nAll settings via `.env` (or Makefile overrides):\n\n```ini\n# Provider: local | nvidia | cloud\nLLM_PROVIDER=nvidia\n\n# Model selection (auto-defaults per provider)\nLLM_MODEL=nvidia/nemotron-3-ultra-550b-a55b\nEMBEDDING_MODEL=nvidia/nv-embed-v1\n\n# Base URLs (auto-defaults)\nLLM_BASE_URL=https://integrate.api.nvidia.com/v1\n\n# API Keys\nNVIDIA_API_KEY=your-key\n# OPENAI_API_KEY=your-key  (for cloud)\n```\n\n**Makefile Overrides:**\n```bash\nmake run PROVIDER=nvidia MODEL=nvidia/llama-3.1-nemotron-70b-instruct\nmake generate PROVIDER=local MODEL=llama3.1:8b\n```\n\n---\n\n## 📁 Project Structure\n\n```\naskode/\n├── Makefile              # Provider-aware orchestration\n├── .env                  # Runtime config (not in git)\n├── src/\n│   └── bot.py           # Chainlit RAG server\n├── scripts/\n│   └── quizgen.py       # Dual-pass Q&A generator\n├── docs/                # Your engineering docs go here\n├── qa_pairs.jsonl       # Generated Q&A (gitignored)\n├── .chroma/             # ChromaDB vector store (gitignored)\n└── chat_history.txt     # Chat logs (gitignored)\n```\n\n---\n\n## 🔧 Make Targets\n\n### Core Pipeline\n| Target | Description |\n|--------|-------------|\n| `make setup` | Install Python deps |\n| `make generate` | Run dual-pass Q&A generation |\n| `make run-local` | Run with Ollama (local) |\n| `make run-nvidia` | Run with NVIDIA API |\n| `make run-cloud` | Run with OpenAI |\n| `make clean` | Remove generated artifacts |\n\n### OKF Knowledge Bundles (AST + Docs)\n| Target | Description |\n|--------|-------------|\n| `make okf-generate-all` | Generate all 4 bundles (code, scripts, strategies, docs) |\n| `make okf-generate-code` | AST-extract `src/` → `code_bundle` |\n| `make okf-generate-scripts` | AST-extract `scripts/` → `scripts_bundle` |\n| `make okf-generate-strategies` | AST-extract `docs/strategies/` → `strategies_bundle` |\n| `make okf-generate-docs` | Convert `docs/*.md` → `docs_bundle` |\n| `make okf-update-all` | Fast incremental update all bundles |\n| `make okf-update-code` | Update `code_bundle` from `src/` |\n| `make okf-update-scripts` | Update `scripts_bundle` from `scripts/` |\n| `make okf-update-strategies` | Update `strategies_bundle` from `docs/strategies/` |\n| `make okf-update-docs` | Update `docs_bundle` from `docs/` |\n| `make okf-watch-code` | Watch `src/` for continuous updates |\n| `make okf-watch-scripts` | Watch `scripts/` for continuous updates |\n| `make okf-watch-strategies` | Watch `docs/strategies/` for continuous updates |\n| `make okf-watch-docs` | Watch `docs/` for continuous updates |\n| `make okf-chunk` | Semantic chunking (Phase 6) |\n| `make okf-embed` | Generate embeddings (Phase 7) |\n| `make okf-index` | Index to ChromaDB (Phase 8) |\n| `make okf-pipeline` | Run chunk → embed → index |\n| `make okf-link` | Add cross-bundle links (docs ↔ code) |\n| `make okf-viz-all` | Visualize all 4 bundles as HTML |\n| `make okf-viz-code` | Visualize `code_bundle` |\n| `make okf-viz-scripts` | Visualize `scripts_bundle` |\n| `make okf-viz-strategies` | Visualize `strategies_bundle` |\n| `make okf-viz-docs` | Visualize `docs_bundle` |\n| `make okf-dashboard` | Live dashboard for `code_bundle` (port 8700) |\n| `make okf-install-agents` | Install OKF skills for Cursor, Copilot, Windsurf, Cline, OpenCode |\n| `make okf-lookup CONCEPT=<name> BUNDLE=<bundle>` | CLI lookup by concept ID |\n\n### OKF Chat (ChromaDB RAG)\n| Target | Description |\n|--------|-------------|\n| `make okf-chat-local` | Chainlit chat with local embeddings (port 3000) |\n| `make okf-chat-nvidia` | Chainlit chat with NVIDIA embeddings |\n| `make okf-chat-cloud` | Chainlit chat with OpenAI embeddings |\n\n### Evaluation\n| Target | Description |\n|--------|-------------|\n| `make okf-eval` | Run retrieval evaluation (concept accuracy + cross-bundle) |\n\n---\n\n## 📋 Requirements\n\n- Python 3.11+\n- For local: Ollama 0.31+ with `mistral-nemo:12b` and `nomic-embed-text`\n- For NVIDIA: API key from [build.nvidia.com](https://build.nvidia.com)\n- For OpenAI: API key from [platform.openai.com](https://platform.openai.com)\n\n---\n\n## 📝 Generated Q&A Format\n\nEach entry in `qa_pairs.jsonl`:\n```json\n{\n  \"id\": \"qa_42\",\n  \"source\": \"architecture.md\",\n  \"question\": \"How does the deployment architecture enforce separation between the Freqtrade engine and user-specific strategy artifacts?\",\n  \"answer\": \"The deployment keeps all user-specific artifacts (strategies, SQLite DBs, configs, policies, logs, reports) outside the container under a host `user_data/` directory...\"\n}\n```\n\n---\n\n## 🎯 Use Cases\n\n- **Onboarding**: New engineers query the codebase via natural language\n- **Architecture Reviews**: Quick lookup of design decisions and data flows\n- **Debugging**: Trace config keys, error handling, and invariants\n- **Knowledge Retention**: Preserve tribal knowledge in queryable form",
  "bytes": 6728,
  "sha": "60fb394ff4d7fc35f106d5d128c5b15295d39736bf103cb97997300592678410",
  "repo_slug": "moinonin/askode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_moinonin_askode_okf_bundle_index_md_8c25feb5/readme"
}