{"id":34100138,"url":"https://github.com/amberlee2427/nancy-brain","last_synced_at":"2026-01-18T05:57:09.831Z","repository":{"id":311367742,"uuid":"1043403236","full_name":"AmberLee2427/nancy-brain","owner":"AmberLee2427","description":"Nancy's RAG backend and HTTP API/MCP server connectors.","archived":false,"fork":false,"pushed_at":"2026-01-17T22:01:04.000Z","size":2260,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T03:35:41.488Z","etag":null,"topics":["embeddings","http","mcp","mcp-server","python","rag","rag-chatbot","sql"],"latest_commit_sha":null,"homepage":"https://amberlee2427.github.io/nancy-brain/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AmberLee2427.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-23T19:23:38.000Z","updated_at":"2026-01-17T17:33:52.000Z","dependencies_parsed_at":"2025-08-24T11:25:51.944Z","dependency_job_id":"c719ee38-8060-4bfb-81dd-75b7c6875ba4","html_url":"https://github.com/AmberLee2427/nancy-brain","commit_stats":null,"previous_names":["amberlee2427/nancy-brain"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/AmberLee2427/nancy-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fnancy-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fnancy-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fnancy-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fnancy-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AmberLee2427","download_url":"https://codeload.github.com/AmberLee2427/nancy-brain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fnancy-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embeddings","http","mcp","mcp-server","python","rag","rag-chatbot","sql"],"created_at":"2025-12-14T16:42:38.151Z","updated_at":"2026-01-18T05:57:09.809Z","avatar_url":"https://github.com/AmberLee2427.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nancy Brain\n\n[Pages](https://amberlee2427.github.io/nancy-brain/) [Read the Docs](https://nancy-brain.readthedocs.io/en/latest/)\n\n**Turn any GitHub repository into a searchable knowledge base for AI agents.**\n\nLoad the complete source code, documentation, examples, and notebooks from any package you're working with. Nancy Brain gives AI assistants instant access to:\n\n- **Full source code** - actual Python classes, methods, implementation details\n- **Live documentation** - tutorials, API docs, usage examples  \n- **Real examples** - Jupyter notebooks, test cases, configuration files\n- **Smart weighting** - boost important docs, learning persists across sessions\n\nThe AI can now answer questions like \"How do I initialize this class?\" or \"Show me an example of fitting a light curve\" with actual code from the repositories you care about.\n\n## 🚀 Quick Start\n\n```bash\n# Install anywhere\npip install nancy-brain\n\n# Initialize a new project\nnancy-brain init my-ai-project\ncd my-ai-project\n\n# Add some repositories  \nnancy-brain add-repo https://github.com/scikit-learn/scikit-learn.git\n\n# Build the knowledge base\nnancy-brain build\n\n# Search it!\nnancy-brain search \"machine learning algorithms\"\n\n# Or launch the web interface\nnancy-brain ui\n```\n\n## 🌐 Web Admin Interface\n\nLaunch the visual admin interface for easy knowledge base management:\n\n```bash\nnancy-brain ui\n```\n\nFeatures:\n- **🔍 Live Search** - Test your knowledge base with instant results\n- **📚 Repository Management** - Add/remove GitHub repos with visual forms\n- **📄 Article Management** - Add/remove PDF articles with visual forms\n- **🏗️ Build Control** - Trigger knowledge base builds with options\n- **📊 System Status** - Check embeddings, configuration, and health\n\nPerfect for non-technical users and rapid prototyping!\n\n## 🖥️ Command Line Interface\n\n```bash\nnancy-brain init \u003cproject\u003e        # Initialize new project\nnancy-brain add-repo \u003curl\u003e        # Add GitHub repositories  \nnancy-brain add-article \u003curl\u003e \u003cname\u003e  # Add PDF articles\nnancy-brain add-new-user \u003cuser\u003e \u003cpass\u003e  # Create login credentials\nnancy-brain build                 # Build knowledge base\nnancy-brain search \"query\"        # Search knowledge base\nnancy-brain serve                 # Start HTTP API server\nnancy-brain ui                    # Launch web admin interface\n```\n\n\n### Chunking\n\nNancy Brain uses the [`chunky-files`](https://pypi.org/project/chunky-files/) package for chunking repositories. Configure chunk boundaries with environment variables before running a build:\n\n| Variable | Purpose | Default |\n| --- | --- | --- |\n| `CHUNKY_LINES_PER_CHUNK` | Maximum lines per chunk window | 80 |\n| `CHUNKY_LINE_OVERLAP` | Overlap between consecutive chunks | 10 |\n| `CHUNKY_MAX_CHARS` | Maximum characters per chunk | 2000 |\n\nTo adjust chunks per file programmatically, supply a custom `ChunkerConfig` through the build pipeline. For advanced semantic chunkers (Tree-sitter, language-specific splits), install extras: `pip install chunky-files[tree]`.\n\n### Optional: Anthropic-powered summaries\n\nSet an API key and opt-in to generate document-level summaries and suggested search weights during a build:\n\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nexport ENABLE_DOC_SUMMARIES=true   # or pass --summaries on the build command\nnancy-brain build --summaries\n```\n\nSummaries are cached under `knowledge_base/cache/summaries/` using the document content hash, so reruns only\ncall Anthropic when files change. Suggested weights are written to `knowledge_base/embeddings/auto_model_weights.json`\nfor review before merging into your active `model_weights.yml`.\n\n## Technical Architecture\n\nA lightweight Retrieval-Augmented Generation (RAG) knowledge base with:\n- Embedding + search pipeline (txtai / FAISS based)\n- HTTP API connector (FastAPI)\n- Model Context Protocol (MCP) server connector (tools for search / retrieve / tree / weight)\n- Dynamic weighting system (extension/path weights + runtime doc preferences)\n\nDesigned to power AI assistants on Slack, IDEs, Claude Desktop, custom GPTs, and any MCP-capable client.\n\n---\n## 1. Installation \u0026 Quick Setup\n\n### For Users (Recommended)\n```bash\n# Install the package\npip install nancy-brain\n\n# Initialize a new project\nnancy-brain init my-knowledge-base\ncd my-knowledge-base\n\n# Add repositories and build\nnancy-brain add-repo https://github.com/your-org/repo.git\nnancy-brain add-article \"https://arxiv.org/pdf/paper.pdf\" \"paper_name\" --description \"Important paper\"\nnancy-brain build\n\n# Launch web interface\nnancy-brain ui\n```\n\n### For Developers\n```bash\n# Clone and install in development mode\ngit clone \u003crepo-url\u003e\ncd nancy-brain\npip install -e .\"[dev]\"\n\n# Test installation\npytest -q\nnancy-brain --help\n```\n\nNote for developers: The build pipeline now requires `docutils` and `pylatexenc` to reliably convert\nreStructuredText (`.rst`) and LaTeX (`.tex`) files to plain text. These are included in the project's\ndependencies (`pyproject.toml`) so `pip install -e .\"[dev]\"` will install them automatically. If you\nprefer to install them manually in your environment, run:\n\n```bash\npip install docutils pylatexenc\n```\n\nDeveloper note (CLI \u0026 tests):\nThe CLI commands and `RAGService` avoid importing heavy ML libraries (such as `txtai` and `torch`) at\nmodule import time. The service defers initializing the embedding `Search` until an embeddings index is\npresent or a command explicitly needs it. This makes running CLI help and most unit tests fast and safe\nin minimal environments. If a test needs a functioning `Search`, mock `rag_core.search` (insert a\ndummy module into `sys.modules['rag_core.search']`) before instantiating `RAGService`.\n\n---\n## 2. Project Layout (Core Parts)\n```\nnancy_brain/                    # Main Python package\n├── cli.py                      # Command line interface\n├── admin_ui.py                 # Streamlit web admin interface\n└── __init__.py                 # Package initialization\n\nconnectors/http_api/app.py      # FastAPI app\nconnectors/mcp_server/          # MCP server implementation\nrag_core/                       # Core service, search, registry, store, types\nscripts/                        # KB build \u0026 management scripts\nconfig/repositories.yml         # Source repository list (input KB)\nconfig/weights.yaml             # Extension + path weighting config\nconfig/model_weights.yaml       # (Optional) static per-doc multipliers\n```\n\n---\n## 3. Configuration\n\n### 3.1 Repositories (`config/repositories.yml`)\nStructure (categories map to lists of repos):\n```yaml\n\u003ccategory_name\u003e:\n  - name: repoA\n    url: https://github.com/org/repoA.git\n  - name: repoB\n    url: https://github.com/org/repoB.git\n```\nCategories become path prefixes inside the knowledge base (e.g. `cat1/repoA/...`).\n\n### 3.2 Weight Config (`config/weights.yaml`)\n- `extensions`: base multipliers by file extension (.py, .md, etc.)\n- `path_includes`: if substring appears in doc_id, multiplier is applied multiplicatively.\n\n### 3.3 Model Weights (`config/model_weights.yaml`)\nOptional static per-document multipliers (legacy / seed). Runtime updates via `/weight` endpoint or MCP `set_weight` tool override or augment in-memory weights.\n\n### 3.4 Environment Variables\nCommon knobs you can export (or place in `config/.env`) to tune builds and the admin UI:\n\n| Var | Purpose | Default / Typical |\n|-----|---------|-------------------|\n| `KMP_DUPLICATE_LIB_OK` | Avoid OpenMP clashes on macOS | TRUE |\n| `USE_DUAL_EMBEDDING` | Enable dual (text + code) embedding scoring | true |\n| `CODE_EMBEDDING_MODEL` | Code embedding model when dual mode enabled | microsoft/codebert-base |\n| `NB_TEXT_EMBEDDING_MODEL` | Override text embedding model path | sentence-transformers/all-MiniLM-L6-v2 |\n| `NB_CODE_EMBEDDING_MODEL` | Override code embedding model path | inherits `CODE_EMBEDDING_MODEL` |\n| `SKIP_PDF_PROCESSING` | Skip PDF downloads/extraction during build | false |\n| `ANTHROPIC_API_KEY` | Enable Anthropic summaries (used with `--summaries`) | unset |\n| `ENABLE_DOC_SUMMARIES` | Toggle summaries in builds by default | false |\n| `NB_SUMMARY_TIMEOUT_SECONDS` | Per-doc summary timeout | 25 |\n| `NB_PER_FILE_LOG` | Log each file’s chunk count (diagnostics) | false |\n| `NB_SKIP_TEST_SEARCH` | Skip post-build sample queries | false |\n| `NB_SECRET_KEY` | JWT signing key for API/UI auth | dev key (change in prod) |\n| `NB_JWT_ALGORITHM` | JWT algorithm | HS256 |\n| `NB_ACCESS_EXPIRE_MINUTES` | Access token lifetime | 60 |\n| `NB_REFRESH_EXPIRE_MINUTES` | Refresh token lifetime | 1440 |\n| `NB_USERS_DB` | SQLite users DB path | users.db |\n| `OMP_NUM_THREADS` / `MKL_NUM_THREADS` / `NUMEXPR_MAX_THREADS` | Cap CPU threading for heavy libs | unset |\n| `TOKENIZERS_PARALLELISM` | Suppress HF tokenizer warning | false |\n\n\u003e Tip: First builds download Hugging Face models; set `NB_TEXT_EMBEDDING_MODEL` to a local path (or run a quick `python - \u003c\u003c'PY' …` prefetch) if your network is slow.\n\n### Creating login users\n\nNancy Brain’s HTTP API and Streamlit UI expect credentials stored in `NB_USERS_DB` (default `users.db`).  \nUse the CLI to add hashed logins without touching the database directly:\n\n```bash\nnancy-brain add-new-user \u003cusername\u003e \u003cpassword\u003e\n```\n\nThe command bootstraps the auth tables (if they do not exist), hashes the password with `passlib`, and saves the record in the configured SQLite file.  \nPoint `NB_USERS_DB` to a shared path before running the command if you need a centralized user store.\n\n---\n## 4. Building the Knowledge Base\nEmbeddings must be built before meaningful search.\n\n### Using the CLI (Recommended)\n```bash\n# Basic build (repositories only)\nnancy-brain build\n\n# Build with PDF articles (if configured)\nnancy-brain build --articles-config config/articles.yml\n\n# Force update all repositories\nnancy-brain build --force-update\n\n# Or use the web interface\nnancy-brain ui  # Go to \"Build Knowledge Base\" page\n```\n\n### Using the Python Script Directly\n```bash\nconda activate nancy-brain\ncd src/nancy-brain\n# Basic build (repositories only)\npython scripts/build_knowledge_base.py \\\n  --config config/repositories.yml \\\n  --embeddings-path knowledge_base/embeddings\n\n# Full build including optional PDF articles (if config/articles.yml exists)\npython scripts/build_knowledge_base.py \\\n  --config config/repositories.yml \\\n  --articles-config config/articles.yml \\\n  --base-path knowledge_base/raw \\\n  --embeddings-path knowledge_base/embeddings \\\n  --force-update \\\n  --dirty\n# You can run without the dirty tag to automatically \n# remove source material after indexing is complete\n```\nRun `python scripts/build_knowledge_base.py -h` for all options.\n\n### 4.1 PDF Articles (Optional Quick Setup)\n1. Create `config/articles.yml` (example):\n```yaml\njournal_articles:\n  - name: Paczynski_1986_ApJ_304_1\n    url: https://ui.adsabs.harvard.edu/link_gateway/1986ApJ...304....1P/PUB_PDF\n    description: Paczynski (1986) – Gravitational microlensing\n```\n2. Install Java (for Tika PDF extraction) – macOS:\n```bash\nbrew install openjdk\nexport JAVA_HOME=\"/opt/homebrew/opt/openjdk\"\nexport PATH=\"$JAVA_HOME/bin:$PATH\"\n```\n3. (Optional fallback only) Install lightweight PDF libs if you skip Java:\n```bash\npip install PyPDF2 pdfplumber\n```\n4. Build with articles (explicit):\n```bash\npython scripts/build_knowledge_base.py --config config/repositories.yml --articles-config config/articles.yml\n```\n5. Keep raw PDFs for inspection: add `--dirty`.\n\nNotes:\n- If Java/Tika not available, script attempts fallback extraction (needs PyPDF2/pdfplumber or fitz).\n- Cleanups remove raw PDFs unless `--dirty` supplied.\n- Article docs are indexed under `journal_articles/\u003ccategory\u003e/\u003cname\u003e`.\n\nKey flags:\n- `--config` path to repositories YAML (was --repositories in older docs)\n- `--articles-config` optional PDF articles YAML\n- `--base-path` where raw repos/PDFs live (default knowledge_base/raw)\n- `--embeddings-path` output index directory\n- `--force-update` re-pull repos / re-download PDFs\n- `--category \u003cname\u003e` limit to one category\n- `--dry-run` show actions without performing\n- `--dirty` keep raw sources (skip cleanup)\n\nThis will:\n1. Clone / update listed repos under `knowledge_base/raw/\u003ccategory\u003e/\u003crepo\u003e`\n2. (Optionally) download PDFs into category directories\n3. Convert notebooks (*.ipynb -\u003e *.nb.txt) if nb4llm available\n4. Extract and normalize text + (optionally) PDF text\n5. Build / update embeddings index at `knowledge_base/embeddings` (and `code_index` if dual embeddings enabled)\n\nRe-run when repositories or articles change.\n\n---\n## 5. Running Services\n\n### Web Admin Interface (Recommended for Getting Started)\n```bash\nnancy-brain ui\n# Opens Streamlit interface at http://localhost:8501\n# Features: search, repo management, build control, status\n```\n\n### HTTP API Server\n```bash\n# Using CLI\nnancy-brain serve\n\n# Or directly with uvicorn\nuvicorn connectors.http_api.app:app --host 0.0.0.0 --port 8000\n```\n\n### MCP Server (for AI Assistants)\n```bash\n# Run MCP stdio server\npython run_mcp_server.py\n```\n\nInitialize service programmatically (example pattern):\n```python\nfrom pathlib import Path\nfrom connectors.http_api.app import initialize_rag_service\ninitialize_rag_service(\n    config_path=Path('config/repositories.yml'),\n    embeddings_path=Path('knowledge_base/embeddings'),\n    weights_path=Path('config/weights.yaml'),\n    use_dual_embedding=True\n)\n```\nThe FastAPI dependency layer will then serve requests.\n\n### Command Line Search\n```bash\n# Quick search from command line\nnancy-brain search \"machine learning algorithms\" --limit 5\n\n# Search with custom paths\nnancy-brain search \"neural networks\" \\\n  --embeddings-path custom/embeddings \\\n  --config custom/repositories.yml\n```\n\n### 5.1 Endpoints (Bearer auth placeholder)\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/health` | Service status |\n| GET | `/version` | Index / build meta |\n| GET | `/search?query=...\u0026limit=N` | Search documents |\n| POST | `/retrieve` | Retrieve passage (doc_id + line range) |\n| POST | `/retrieve/batch` | Batch retrieve |\n| GET | `/tree?prefix=...` | List KB tree |\n| POST | `/weight` | Set runtime doc weight |\n\nExample:\n```bash\ncurl -H \"Authorization: Bearer TEST\" 'http://localhost:8000/search?query=light%20curve\u0026limit=5'\n```\n\n## Admin UI Authentication\n\nThe Streamlit admin UI supports HTTP API authentication (recommended) and a\nconvenience insecure bypass for local development.\n\n- To use the HTTP API for auth, ensure your API is running and set `NB_API_URL` if not using the default:\n\n```bash\nexport NB_API_URL=\"http://localhost:8000\"\nstreamlit run nancy_brain/admin_ui.py\n```\n\n- For local development without an API, enable an insecure bypass (only use locally):\n\n```bash\nexport NB_ALLOW_INSECURE=true\nstreamlit run nancy_brain/admin_ui.py\n```\n\nThe admin UI stores the access token and refresh token in `st.session_state` for the current Streamlit session.\n\nSet a document weight (boost factor 0.5–2.0 typical):\n```bash\ncurl -X POST -H 'Authorization: Bearer TEST' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"doc_id\":\"cat1/repoA/path/file.py\",\"multiplier\":2.0}' \\\n  http://localhost:8000/weight\n```\n\n---\n## 6. MCP Server\nRun the MCP stdio server:\n```bash\npython run_mcp_server.py\n```\nTools exposed (operation names):\n- `search` (query, limit)\n- `retrieve` (doc_id, start, end)\n- `retrieve_batch`\n- `tree` (prefix, depth)\n- `set_weight` (doc_id, multiplier)\n- `status` / `version`\n\n### 6.1 VS Code Integration\n1. Install a Model Context Protocol client extension (e.g. \"MCP Explorer\" or equivalent).\n2. Add a server entry pointing to the script, stdio transport. Example config snippet:\n```\n{\n  \"mcpServers\": {\n    \"nancy-brain\": {\n      \"command\": \"python\",\n      \"args\": [\"/absolute/path/to/src/nancy-brain/run_mcp_server.py\"],\n      \"env\": {\n        \"PYTHONPATH\": \"/absolute/path/to/src/nancy-brain\" \n      }\n    }\n  }\n}\n```\n\n*Specific mamba environment example:*\n\n```\n{\n\t\"servers\": {\n\t\t\"nancy-brain\": {\n\t\t\t\"type\": \"stdio\",\n\t\t\t\"command\": \"/Users/malpas.1/.local/share/mamba/envs/nancy-brain/bin/python\",\n\t\t\t\"args\": [\n\t\t\t\t\"/Users/malpas.1/Code/slack-bot/src/nancy-brain/run_mcp_server.py\"\n\t\t\t],\n\t\t\t\"env\": {\n\t\t\t\t\"PYTHONPATH\": \"/Users/malpas.1/Code/slack-bot/src/nancy-brain\",\n\t\t\t\t\"KMP_DUPLICATE_LIB_OK\": \"TRUE\"\n\t\t\t}\n\t\t}\n\t},\n\t\"inputs\": []\n}\n```\n\n3. Reload VS Code. The provider should list the tools; invoke `search` to test.\n\n### 6.2 Claude Desktop\nClaude supports MCP config in its settings file. Add an entry similar to above (command + args). Restart Claude Desktop; tools appear in the prompt tools menu.\n\n---\n## 7. Use Cases \u0026 Examples\n\n### For Researchers\n```bash\n# Add astronomy packages\nnancy-brain add-repo https://github.com/astropy/astropy.git\nnancy-brain add-repo https://github.com/rpoleski/MulensModel.git\n\n# Add key research papers\nnancy-brain add-article \\\n  \"https://ui.adsabs.harvard.edu/link_gateway/1986ApJ...304....1P/PUB_PDF\" \\\n  \"Paczynski_1986_microlensing\" \\\n  --category \"foundational_papers\" \\\n  --description \"Paczynski (1986) - Gravitational microlensing by the galactic halo\"\n\nnancy-brain build\n\n# AI can now answer: \"How do I model a microlensing event?\"\nnancy-brain search \"microlensing model fit\"\n```\n\n### For ML Engineers  \n```bash\n# Add ML frameworks\nnancy-brain add-repo https://github.com/scikit-learn/scikit-learn.git\nnancy-brain add-repo https://github.com/pytorch/pytorch.git\nnancy-brain build\n\n# AI can now answer: \"Show me gradient descent implementation\"\nnancy-brain search \"gradient descent optimizer\"\n```\n\n### For Teams\n```bash\n# Launch web interface for non-technical users\nnancy-brain ui\n# Point team to http://localhost:8501\n# They can search, add repos, manage articles, trigger builds visually\n# Repository Management tab: Add GitHub repos\n# Articles tab: Add PDF papers and documents\n```\n\n---\n## 8. Slack Bot (Nancy)\nThe Slack-facing assistant lives outside this submodule (see parent repository). High-level steps:\n1. Ensure HTTP API running and reachable (or embed service directly in bot process).\n2. Bot receives user message -\u003e constructs query -\u003e calls `/search` and selected `/retrieve` for context.\n3. Bot composes answer including source references (doc_id and GitHub URL) before sending back.\n4. Optional: adaptively call `/weight` when feedback indicates a source should be boosted or dampened.\n\nCheck root-level `nancy_bot.py` or Slack integration docs (`SLACK.md`) for token setup and event subscription details.\n\n---\n## 9. Custom GPT (OpenAI Actions / Function Calls)\nDefine OpenAI tool specs mapping to HTTP endpoints:\n- `searchDocuments(query, limit)` -\u003e GET /search\n- `retrievePassage(doc_id, start, end)` -\u003e POST /retrieve\n- `listTree(prefix, depth)` -\u003e GET /tree\n- `setWeight(doc_id, multiplier)` -\u003e POST /weight\n\nUse an API gateway or direct URL. Include auth header. Provide JSON schemas matching request/response models.\n\n---\n## 10. Dynamic Weighting Flow\n1. Base score from embeddings (dual or single).\n2. Extension multiplier (from weights.yaml).\n3. Path multiplier(s) (cumulative).\n4. Model weight (static config + runtime overrides via `/weight`).\n5. Adjusted score = base * extension_weight * model_weight (and any path multipliers folded into extension weight step).\n\nRuntime `/weight` takes effect immediately on subsequent searches.\n\n---\n## 11. Updating / Rebuilding\n| Action | Command |\n|--------|---------|\n| Pull repo updates | `nancy-brain build --force-update` or re-run build script |\n| Change extension weights | Edit `config/weights.yaml` (no restart needed for runtime? restart or rebuild if cached) |\n| Change embedding model | Delete / rename existing `knowledge_base/embeddings` and rebuild with new env vars |\n\n---\n## 12. Deployment Notes\n- Containerize: build image with pre-built embeddings baked or mount a persistent volume.\n- Health probe: `/health` (returns 200 once rag_service initialized) else 503.\n- Concurrency: FastAPI async safe; weight updates are simple dict writes (low contention). For heavy load consider a lock if races appear.\n- Persistence of runtime weights: currently in-memory; persist manually if needed (extend `set_weight`).\n\n---\n## 13. Troubleshooting\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| 503 RAG service not initialized | `initialize_rag_service` not called / wrong paths | Call initializer with correct embeddings path |\n| Empty search results | Embeddings not built / wrong path | Re-run `nancy-brain build`, verify index directory |\n| macOS OpenMP crash | MKL / libomp duplicate | `KMP_DUPLICATE_LIB_OK=TRUE` already set early |\n| MCP tools not visible | Wrong path or PYTHONPATH | Use absolute paths in MCP config |\n| CLI command not found | Package not installed | `pip install nancy-brain` |\n\nEnable debug logging:\n```bash\nexport LOG_LEVEL=DEBUG\n```\n(add logic or run with `uvicorn --log-level debug`)\n\n---\n## 14. Development \u0026 Contributing\n```bash\n# Clone and set up development environment\ngit clone \u003crepo-url\u003e\ncd nancy-brain\npip install -e .\"[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nblack nancy_brain/ \nflake8 nancy_brain/\n\n# Test CLI locally\nnancy-brain --help\n```\n\n### Releasing\nNancy Brain uses automated versioning and PyPI publishing:\n\n```bash\n# Bump patch version (0.1.0 → 0.1.1)\n./release.sh patch\n\n# Bump minor version (0.1.0 → 0.2.0)  \n./release.sh minor\n\n# Bump major version (0.1.0 → 1.0.0)\n./release.sh major\n```\n\nThis automatically:\n1. Updates version numbers in `pyproject.toml` and `nancy_brain/__init__.py`\n2. Creates a git commit and tag\n3. Pushes to GitHub, triggering PyPI publication via GitHub Actions\n\nManual version management:\n```bash\n# See current version and bump options\nbump-my-version show-bump\n\n# Dry run (see what would change)\nbump-my-version bump --dry-run patch\n```\n\n---\n## 15. Roadmap (Optional)\n- Persistence layer for runtime weights\n- Additional retrieval filters (e.g. semantic rerank)\n- Auth plugin / token validation\n- VS Code extension\n- Package publishing to PyPI\n\n---\n## 16. License\nSee parent repository license.\n\n---\n## 17. Minimal Verification Script\n```bash\n# After build \u0026 run\ncurl -H 'Authorization: Bearer TEST' 'http://localhost:8000/health'\n```\nExpect JSON with status + trace_id.\n\n---\nHappy searching.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003c!-- Badges Dashbord to check for issues, PRs, and health of CI tests and docs builds --\u003e\n[![GitHub license](https://img.shields.io/github/license/amberlee2427/nancy-brain)](https://github.com/amberlee2427/nancy-brain/blob/main/LICENSE) [![GitHub issues](https://img.shields.io/github/issues/amberlee2427/nancy-brain)](https://github.com/amberlee2427/nancy-brain/issues) [![GitHub releases](https://img.shields.io/github/releases/amberlee2427/nancy-brain)](https://github.com/amberlee2427/nancy-brain/releases) [![GitHub status](https://github.com/amberlee2427/nancy-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/amberlee2427/nancy-brain/actions/workflows/ci.yml) [![docs status](https://github.com/amberlee2427/nancy-brain/actions/workflows/docs.yml/badge.svg)](https://github.com/amberlee2427/nancy-brain/actions/workflows/docs.yml)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famberlee2427%2Fnancy-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famberlee2427%2Fnancy-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famberlee2427%2Fnancy-brain/lists"}