knowledge-master 0.1.0__py3-none-any.whl

knowledge_master-0.1.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: knowledge-master
+Version: 0.1.0
+Summary: Local-first knowledge graph for developers. Your AI agent's permanent memory.
+Author: Milenko Mitrovic
+License: MIT
+Project-URL: Homepage, https://github.com/subzone/knowledge-master
+Project-URL: Repository, https://github.com/subzone/knowledge-master
+Project-URL: Issues, https://github.com/subzone/knowledge-master/issues
+Keywords: rag,knowledge-graph,mcp,ai,developer-tools,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: falkordb<2.0,>=1.6.0
+Requires-Dist: ollama<1.0,>=0.4.0
+Requires-Dist: mcp<2.0,>=1.9.0
+Requires-Dist: typer<1.0,>=0.15.0
+Requires-Dist: gitpython<4.0,>=3.1.0
+Requires-Dist: rich<15.0,>=14.0.0
+Requires-Dist: fastapi<1.0,>=0.115.0
+Requires-Dist: uvicorn<1.0,>=0.34.0
+Provides-Extra: office
+Requires-Dist: python-docx<2.0,>=1.1.0; extra == "office"
+Requires-Dist: openpyxl<4.0,>=3.1.0; extra == "office"
+Requires-Dist: pypdf<6.0,>=5.0; extra == "office"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Dynamic: license-file
+
+# ⚡ Knowledge Master
+
+**Your codebase's memory.** A local knowledge graph that gives AI agents real understanding of your architecture — not just text search.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## Why
+
+Every time you start a new AI chat, it forgets everything. You re-explain your architecture, conventions, dependencies. Knowledge Master gives your AI **permanent, structured memory** about your entire system.
+
+Unlike flat RAG tools that return "chunks about X", Knowledge Master builds a **graph** — so it can answer "what breaks if I change X?" by traversing actual relationships.
+
+## What it does
+
+- 🔍 **Semantic search** across all your code, docs, and configs
+- 🕸️ **Knowledge graph** — relationships between services, people, repos, technologies
+- 💥 **Blast radius** — "what depends on this service/file/technology?"
+- 📏 **Convention enforcement** — detects and enforces your team's patterns
+- 🤖 **MCP server** — plugs directly into AI agents (Kiro, Claude, Cursor)
+- 🖥️ **Web UI** — search, browse, visualize your knowledge graph
+- 🔒 **Local-first** — nothing leaves your machine
+
+## Prerequisites
+
+| Dependency | macOS | Ubuntu/Debian | Windows |
+|---|---|---|---|
+| **Docker** | `brew install colima && colima start` or Docker Desktop | `sudo apt install docker.io docker-compose-plugin` | [Docker Desktop](https://docker.com/products/docker-desktop/) |
+| **Ollama** | `brew install ollama && ollama serve` | `curl -fsSL https://ollama.com/install.sh \| sh` | [Ollama installer](https://ollama.com/download) |
+| **Python 3.11+** | `brew install python@3.12` | `sudo apt install python3.12 python3.12-venv` | [python.org](https://python.org/downloads/) |
+
+## Quick Start
+
+```bash
+# Install (pick one)
+pip install knowledge-master          # from PyPI
+pipx install knowledge-master         # isolated install (recommended)
+
+# Or from source
+git clone https://github.com/subzone/knowledge-master.git
+cd knowledge-master
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+# One command setup
+km start
+
+# Index your first repo
+km index ~/path/to/your/project
+
+# Search
+km search "authentication flow"
+
+# Check blast radius
+km blast-radius postgres
+
+# Start web UI with graph visualization
+km serve
+```
+
+**Requirements:** Docker, Ollama, Python 3.11+
+
+## Features
+
+### Semantic Search with Graph Context
+```bash
+$ km search "how does auth work"
+┌────────┬──────────────────────┬─────────────────────┬──────────────────────┐
+│ Score  │ Source               │ Context             │ Preview              │
+├────────┼──────────────────────┼─────────────────────┼──────────────────────┤
+│ 0.847  │ src/auth/service.py  │ repo:myapp, by:Alex │ JWT token validat... │
+│ 0.791  │ docs/auth.md         │ repo:myapp          │ Authentication f...  │
+└────────┴──────────────────────┴─────────────────────┴──────────────────────┘
+```
+
+### Blast Radius Analysis
+```bash
+$ km blast-radius auth-service
+💥 Blast radius: auth-service
+├── ⚙️ user-service (Service, via DEPENDS_ON)
+├── ⚙️ payment-service (Service, via DEPENDS_ON)
+├── 📦 frontend (Repo, via USES_SERVICE)
+└── 👤 Alex (Person, via AUTHORED)
+
+4 entities affected
+```
+
+### Convention Enforcement
+```bash
+$ km check-conventions ~/my-project
+  ✓ src/ directory (structure)
+  ✓ separate test directory (testing)
+  ✗ snake_case files (file-naming)
+  ✓ Repository pattern (design-pattern)
+
+1 convention(s) violated
+```
+
+### Web UI & Graph Visualization
+
+```bash
+$ km serve
+Knowledge Master UI → http://127.0.0.1:9999
+```
+
+Interactive force-directed graph showing your entire knowledge topology:
+- 📦 Repos (blue) → 🔧 Technologies (red)
+- ⚙️ Services (orange) → Dependencies
+- 👤 People → Authorship
+- 📏 Conventions (purple)
+
+### MCP Integration (AI Agents)
+
+Add to your Kiro/Claude agent config:
+
+```json
+{
+  "mcpServers": {
+    "knowledge": {
+      "command": "km-server"
+    }
+  }
+}
+```
+
+Your AI agent gets these tools:
+- `search` — semantic search with graph context
+- `blast_radius` — dependency analysis
+- `check_conventions` — verify code follows team patterns
+- `index_repo` — add new repos to the knowledge base
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                  Your AI Agent                    │
+│              (Kiro / Claude / Cursor)             │
+└────────────────────┬────────────────────────────┘
+                     │ MCP Protocol
+┌────────────────────▼────────────────────────────┐
+│              Knowledge Master                    │
+│                                                  │
+│  ┌──────────┐  ┌────────────┐  ┌────────────┐  │
+│  │  Search  │  │Blast Radius│  │ Conventions│  │
+│  └────┬─────┘  └─────┬──────┘  └─────┬──────┘  │
+│       │               │               │         │
+│  ┌────▼───────────────▼───────────────▼──────┐  │
+│  │            FalkorDB (Graph + Vector)       │  │
+│  │                                           │  │
+│  │  [Repo]──USES_TECH──▶[Tech]              │  │
+│  │    │                                      │  │
+│  │    ├──DEFINES_SERVICE──▶[Service]         │  │
+│  │    │                      │               │  │
+│  │    ├──FOLLOWS──▶[Convention]              │  │
+│  │    │                                      │  │
+│  │  [Person]──AUTHORED──▶[Document]          │  │
+│  │                          │                │  │
+│  │                    [Chunk + Embedding]     │  │
+│  └───────────────────────────────────────────┘  │
+│                                                  │
+│  ┌───────────────────────────────────────────┐  │
+│  │         Ollama (nomic-embed-text)          │  │
+│  └───────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────┘
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `km start` | Boot Docker containers + pull embedding model |
+| `km stop` | Stop containers |
+| `km index <path>` | Index a git repo or docs directory |
+| `km search <query>` | Semantic search with graph context |
+| `km blast-radius <target>` | Show dependencies and affected entities |
+| `km check-conventions <path>` | Verify code follows detected patterns |
+| `km list` | Show indexed repos, techs, stats |
+| `km remove <name>` | Remove a source from the knowledge base |
+| `km serve` | Start web UI at http://127.0.0.1:9999 |
+| `km status` | Check system health |
+
+## What gets extracted automatically
+
+When you index a repo, Knowledge Master detects:
+
+| Category | Examples |
+|---|---|
+| **Tech stack** | Languages, frameworks, packages from dependency files |
+| **Services** | From docker-compose.yml and K8s manifests |
+| **Dependencies** | Service-to-service relationships |
+| **Conventions** | File naming (snake_case/kebab-case), folder structure, design patterns |
+| **People** | Git commit authors and file ownership |
+| **Code structure** | Functions, classes, chunked by AST-aware boundaries |
+
+## Comparison
+
+| Feature | Knowledge Master | Generic RAG | GitHub Copilot | Glean |
+|---|---|---|---|---|
+| Graph relationships | ✅ | ❌ | ❌ | Partial |
+| Blast radius analysis | ✅ | ❌ | ❌ | ❌ |
+| Convention enforcement | ✅ | ❌ | ❌ | ❌ |
+| Local-first (no cloud) | ✅ | ✅ | ❌ | ❌ |
+| MCP integration | ✅ | ❌ | ❌ | ❌ |
+| Multi-repo intelligence | ✅ | Partial | ❌ | ✅ |
+| Cost | Free | Free | $19/mo | $15-30/mo |
+
+## Development
+
+```bash
+# Run tests
+pytest
+
+# Lint
+ruff check knowledge_master/
+
+# Run MCP server directly
+python -m knowledge_master.server
+
+# Run CLI directly
+python -m knowledge_master.cli status
+```
+
+## Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| `km start` fails with "Docker not running" | Start Docker: `colima start` (macOS) or `sudo systemctl start docker` (Linux) |
+| `km start` fails with "Ollama not found" | Install Ollama from https://ollama.com and run `ollama serve` |
+| `km index` is slow | First run downloads the embedding model (~274MB). Subsequent runs are fast. |
+| Web UI shows "Connection refused" | Make sure containers are running: `km start` |
+| Search returns poor results | Index more content. Quality improves with more context in the graph. |
+| Port 9999 already in use | Use `km serve --port 8888` |
+
+## License
+
+MIT

knowledge_master-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+knowledge_master/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+knowledge_master/__main__.py,sha256=ascEuJ4Ydlmo-iAW3yo4mVGarLsCiMwIS4cu7TgYNRk,79
+knowledge_master/chunking.py,sha256=BkfmlM5WBfinn91Vsx0seBnpC2d5gT19RRGdQhet2yw,3412
+knowledge_master/cli.py,sha256=kL5Bjp29NlDEix6lnPJovKWjnvTNAE0ToOWFYCZCRII,12680
+knowledge_master/embeddings.py,sha256=mrjSNeh_pHg0V9AkxpHD1_7AQBD_MLVXJE-gpghk5q0,629
+knowledge_master/intelligence.py,sha256=hm4qOQGROOEa1PJ_yRNDzzRmak3n6NCQMdHNnBjYDdU,9987
+knowledge_master/server.py,sha256=A2cR0S9QZ1UriRfk1cWsEtUCXQis5-jLF7DashAJDi0,7692
+knowledge_master/store.py,sha256=GT-CMiXTHppiENzxRlmXLlNsYmiUYga6mcA_6wNUZCQ,5637
+knowledge_master/watcher.py,sha256=9TVOm8O7iAnpdQANryCGTe-FmVlJIIw3AJVInpx7K5c,3354
+knowledge_master/web.py,sha256=B_CpokEW3vFoB12jmjYVzmm8Nh5o0sWV4FlssTSygQg,26461
+knowledge_master/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+knowledge_master/parsers/git_repo.py,sha256=M2E1e4fkNdVqcXYHxbuJu85PwHG1P4K2rQy0scKW6jk,3804
+knowledge_master/parsers/markdown.py,sha256=gtpJHlJt1l4ZM8O8EZgS2svf4RA7mh040P2mBBm4c9s,1813
+knowledge_master-0.1.0.dist-info/licenses/LICENSE,sha256=k8iRlncDZZI9fHjoCQQ7BQoFRrxyrQ4cnKJf_z4nyVY,1073
+knowledge_master-0.1.0.dist-info/METADATA,sha256=9jdKEFo0wanaF5OkFHFm12OfL5iwkABj3mMYmPbQQbo,11504
+knowledge_master-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+knowledge_master-0.1.0.dist-info/entry_points.txt,sha256=QSbaSSsZsKpHD7A9o9XHwbyoy2tshSLsqCfPOBIn3Qk,89
+knowledge_master-0.1.0.dist-info/top_level.txt,sha256=Bj6XTrpApc4mQFqLdLoYLM7tHRthRfnZQ0AxE-eD6VY,17
+knowledge_master-0.1.0.dist-info/RECORD,,

knowledge_master-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

knowledge_master-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+km = knowledge_master.cli:app
+km-server = knowledge_master.server:main

knowledge_master-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Milenko Mitrovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

knowledge_master-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+knowledge_master