codebase-cortex 0.1.0__tar.gz

codebase_cortex-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment
+.env
+
+# Codebase Cortex per-repo data
+.cortex/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store

codebase_cortex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarupuri Sai Lalith
+
+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.

codebase_cortex-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: codebase-cortex
+Version: 0.1.0
+Summary: AI-powered documentation autopilot — commit code, docs update themselves. Five LangGraph agents analyze diffs, find related code via FAISS embeddings, and sync Notion pages through MCP.
+Project-URL: Homepage, https://github.com/sarupurisailalith/codebase-cortex
+Project-URL: Repository, https://github.com/sarupurisailalith/codebase-cortex
+Project-URL: Documentation, https://github.com/sarupurisailalith/codebase-cortex/tree/main/docs
+Project-URL: Issues, https://github.com/sarupurisailalith/codebase-cortex/issues
+Author-email: Sailalith Sarupuri <sarupurisailalith@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,automation,code-analysis,developer-tools,docs-as-code,documentation,embeddings,faiss,git,langgraph,mcp,model-context-protocol,multi-agent,notion,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: faiss-cpu>=1.8
+Requires-Dist: gitpython>=3.1
+Requires-Dist: hdbscan>=0.8
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-anthropic>=0.3
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-google-genai>=2.1
+Requires-Dist: langchain-mcp-adapters>=0.1
+Requires-Dist: langchain-openai>=0.3
+Requires-Dist: langgraph>=0.3
+Requires-Dist: mcp>=1.0
+Requires-Dist: pygithub>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sentence-transformers>=3.0
+Description-Content-Type: text/markdown
+
+# Codebase Cortex
+
+**Automatically keep your engineering documentation in sync with code.**
+
+Codebase Cortex is a multi-agent system that watches your codebase for changes and updates your Notion documentation automatically. It uses LangGraph to orchestrate five specialized AI agents that analyze code, find related docs, write updates, create tasks, and generate sprint reports — all through the [Notion MCP](https://developers.notion.com/docs/mcp) protocol.
+
+```mermaid
+graph LR
+    A[Git Commit] --> B[CodeAnalyzer]
+    B --> C[SemanticFinder]
+    C --> D[DocWriter]
+    D --> E[TaskCreator]
+    E --> F[SprintReporter]
+    F --> G[Notion Workspace]
+```
+
+## Features
+
+- **Automatic doc sync** — Commit code, docs update themselves via post-commit hook
+- **Section-level updates** — Only changed sections are rewritten, preserving the rest
+- **Semantic search** — FAISS embeddings find related code across your entire codebase
+- **Natural language prompts** — `cortex prompt "Add more API examples"` to direct updates
+- **Multi-page intelligence** — Agents understand relationships across all your doc pages
+- **Sprint reports** — Weekly summaries generated from commit activity
+- **Task tracking** — Automatically identifies undocumented areas and creates Notion tasks
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) package manager
+- A Notion account (free plan works)
+- An LLM API key (Google Gemini, Anthropic, or OpenRouter)
+
+### Install
+
+```bash
+# Install from PyPI
+pip install codebase-cortex
+
+# Or with uv
+uv tool install codebase-cortex
+```
+
+Both `cortex` and `codebase-cortex` commands are available after installation. If `cortex` conflicts with another package on your system, use `codebase-cortex` instead.
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+git clone https://github.com/sarupurisailalith/codebase-cortex.git
+cd codebase-cortex
+uv sync
+uv tool install .
+```
+</details>
+
+### Initialize in your project
+
+```bash
+cd /path/to/your-project
+
+# Interactive setup — connects to Notion, configures LLM, creates starter pages
+cortex init
+
+# Run the pipeline
+cortex run --once
+```
+
+The `init` wizard will:
+1. Ask for your LLM provider and API key
+2. Open a browser for Notion OAuth authorization
+3. Create starter documentation pages in Notion
+4. Optionally install a post-commit git hook
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `cortex init` | Interactive setup wizard |
+| `cortex run --once` | Run the full pipeline once |
+| `cortex run --once --full` | Full codebase analysis (not just recent diff) |
+| `cortex run --once --dry-run` | Analyze without writing to Notion |
+| `cortex prompt "instruction"` | Natural language doc updates |
+| `cortex prompt "..." -p "Page"` | Target specific page(s) |
+| `cortex status` | Show connection and config status |
+| `cortex analyze` | One-shot diff analysis (no Notion writes) |
+| `cortex embed` | Rebuild the FAISS embedding index |
+| `cortex scan` | Discover existing Notion pages |
+| `cortex scan --link <id>` | Link a specific Notion page |
+
+## How It Works
+
+Cortex creates a `.cortex/` directory (gitignored) in your project repo that stores configuration, OAuth tokens, and the FAISS vector index. When you run the pipeline, five agents work in sequence:
+
+```mermaid
+graph TD
+    START([Start]) --> CA[CodeAnalyzer]
+    CA -->|Has analysis?| SF[SemanticFinder]
+    CA -->|No changes| END1([End])
+    SF --> DW[DocWriter]
+    DW --> TC[TaskCreator]
+    TC -->|Has updates?| SR[SprintReporter]
+    TC -->|Nothing to report| END2([End])
+    SR --> END3([End])
+
+    style CA fill:#4A90D9,color:#fff
+    style SF fill:#7B68EE,color:#fff
+    style DW fill:#50C878,color:#fff
+    style TC fill:#FFB347,color:#fff
+    style SR fill:#FF6B6B,color:#fff
+```
+
+1. **CodeAnalyzer** — Parses git diffs (or scans the full codebase) and produces a structured analysis of what changed
+2. **SemanticFinder** — Embeds the analysis and searches the FAISS index to find semantically related code chunks
+3. **DocWriter** — Fetches current Notion pages, generates section-level updates, and merges them deterministically
+4. **TaskCreator** — Identifies undocumented areas and creates task pages in Notion
+5. **SprintReporter** — Synthesizes all activity into a weekly sprint summary
+
+## Architecture
+
+For detailed architecture documentation, see [`docs/architecture.md`](docs/architecture.md).
+
+## Per-Repo Configuration
+
+```
+your-project/
+├── .cortex/                    # Created by cortex init (gitignored)
+│   ├── .env                    # LLM provider, API keys
+│   ├── .gitignore              # Ignores everything in .cortex/
+│   ├── notion_tokens.json      # OAuth tokens (auto-refreshed)
+│   ├── page_cache.json         # Tracked Notion pages
+│   └── faiss_index/            # Vector embeddings
+│       ├── index.faiss
+│       └── chunks.json
+├── src/
+└── ...
+```
+
+## Supported LLM Providers
+
+| Provider | Models | Config Key |
+|----------|--------|------------|
+| Google Gemini | gemini-2.5-flash-lite, gemini-3-flash-preview, gemini-2.5-pro | `GOOGLE_API_KEY` |
+| Anthropic | claude-sonnet-4, claude-haiku-4.5 | `ANTHROPIC_API_KEY` |
+| OpenRouter | Any model via OpenRouter | `OPENROUTER_API_KEY` |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/architecture.md) | System design, data flow, agent pipeline |
+| [CLI Reference](docs/cli-reference.md) | All commands, options, and examples |
+| [Agents](docs/agents.md) | How each agent works |
+| [Configuration](docs/configuration.md) | Setup, LLM providers, environment variables |
+| [Notion Integration](docs/notion-integration.md) | OAuth flow, MCP protocol, page management |
+| [Embeddings & Search](docs/embeddings.md) | FAISS index, semantic search, HDBSCAN clustering |
+| [Contributing](docs/contributing.md) | Development setup, testing, project structure |
+
+## License
+
+MIT

codebase_cortex-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Codebase Cortex
+
+**Automatically keep your engineering documentation in sync with code.**
+
+Codebase Cortex is a multi-agent system that watches your codebase for changes and updates your Notion documentation automatically. It uses LangGraph to orchestrate five specialized AI agents that analyze code, find related docs, write updates, create tasks, and generate sprint reports — all through the [Notion MCP](https://developers.notion.com/docs/mcp) protocol.
+
+```mermaid
+graph LR
+    A[Git Commit] --> B[CodeAnalyzer]
+    B --> C[SemanticFinder]
+    C --> D[DocWriter]
+    D --> E[TaskCreator]
+    E --> F[SprintReporter]
+    F --> G[Notion Workspace]
+```
+
+## Features
+
+- **Automatic doc sync** — Commit code, docs update themselves via post-commit hook
+- **Section-level updates** — Only changed sections are rewritten, preserving the rest
+- **Semantic search** — FAISS embeddings find related code across your entire codebase
+- **Natural language prompts** — `cortex prompt "Add more API examples"` to direct updates
+- **Multi-page intelligence** — Agents understand relationships across all your doc pages
+- **Sprint reports** — Weekly summaries generated from commit activity
+- **Task tracking** — Automatically identifies undocumented areas and creates Notion tasks
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) package manager
+- A Notion account (free plan works)
+- An LLM API key (Google Gemini, Anthropic, or OpenRouter)
+
+### Install
+
+```bash
+# Install from PyPI
+pip install codebase-cortex
+
+# Or with uv
+uv tool install codebase-cortex
+```
+
+Both `cortex` and `codebase-cortex` commands are available after installation. If `cortex` conflicts with another package on your system, use `codebase-cortex` instead.
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+git clone https://github.com/sarupurisailalith/codebase-cortex.git
+cd codebase-cortex
+uv sync
+uv tool install .
+```
+</details>
+
+### Initialize in your project
+
+```bash
+cd /path/to/your-project
+
+# Interactive setup — connects to Notion, configures LLM, creates starter pages
+cortex init
+
+# Run the pipeline
+cortex run --once
+```
+
+The `init` wizard will:
+1. Ask for your LLM provider and API key
+2. Open a browser for Notion OAuth authorization
+3. Create starter documentation pages in Notion
+4. Optionally install a post-commit git hook
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `cortex init` | Interactive setup wizard |
+| `cortex run --once` | Run the full pipeline once |
+| `cortex run --once --full` | Full codebase analysis (not just recent diff) |
+| `cortex run --once --dry-run` | Analyze without writing to Notion |
+| `cortex prompt "instruction"` | Natural language doc updates |
+| `cortex prompt "..." -p "Page"` | Target specific page(s) |
+| `cortex status` | Show connection and config status |
+| `cortex analyze` | One-shot diff analysis (no Notion writes) |
+| `cortex embed` | Rebuild the FAISS embedding index |
+| `cortex scan` | Discover existing Notion pages |
+| `cortex scan --link <id>` | Link a specific Notion page |
+
+## How It Works
+
+Cortex creates a `.cortex/` directory (gitignored) in your project repo that stores configuration, OAuth tokens, and the FAISS vector index. When you run the pipeline, five agents work in sequence:
+
+```mermaid
+graph TD
+    START([Start]) --> CA[CodeAnalyzer]
+    CA -->|Has analysis?| SF[SemanticFinder]
+    CA -->|No changes| END1([End])
+    SF --> DW[DocWriter]
+    DW --> TC[TaskCreator]
+    TC -->|Has updates?| SR[SprintReporter]
+    TC -->|Nothing to report| END2([End])
+    SR --> END3([End])
+
+    style CA fill:#4A90D9,color:#fff
+    style SF fill:#7B68EE,color:#fff
+    style DW fill:#50C878,color:#fff
+    style TC fill:#FFB347,color:#fff
+    style SR fill:#FF6B6B,color:#fff
+```
+
+1. **CodeAnalyzer** — Parses git diffs (or scans the full codebase) and produces a structured analysis of what changed
+2. **SemanticFinder** — Embeds the analysis and searches the FAISS index to find semantically related code chunks
+3. **DocWriter** — Fetches current Notion pages, generates section-level updates, and merges them deterministically
+4. **TaskCreator** — Identifies undocumented areas and creates task pages in Notion
+5. **SprintReporter** — Synthesizes all activity into a weekly sprint summary
+
+## Architecture
+
+For detailed architecture documentation, see [`docs/architecture.md`](docs/architecture.md).
+
+## Per-Repo Configuration
+
+```
+your-project/
+├── .cortex/                    # Created by cortex init (gitignored)
+│   ├── .env                    # LLM provider, API keys
+│   ├── .gitignore              # Ignores everything in .cortex/
+│   ├── notion_tokens.json      # OAuth tokens (auto-refreshed)
+│   ├── page_cache.json         # Tracked Notion pages
+│   └── faiss_index/            # Vector embeddings
+│       ├── index.faiss
+│       └── chunks.json
+├── src/
+└── ...
+```
+
+## Supported LLM Providers
+
+| Provider | Models | Config Key |
+|----------|--------|------------|
+| Google Gemini | gemini-2.5-flash-lite, gemini-3-flash-preview, gemini-2.5-pro | `GOOGLE_API_KEY` |
+| Anthropic | claude-sonnet-4, claude-haiku-4.5 | `ANTHROPIC_API_KEY` |
+| OpenRouter | Any model via OpenRouter | `OPENROUTER_API_KEY` |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/architecture.md) | System design, data flow, agent pipeline |
+| [CLI Reference](docs/cli-reference.md) | All commands, options, and examples |
+| [Agents](docs/agents.md) | How each agent works |
+| [Configuration](docs/configuration.md) | Setup, LLM providers, environment variables |
+| [Notion Integration](docs/notion-integration.md) | OAuth flow, MCP protocol, page management |
+| [Embeddings & Search](docs/embeddings.md) | FAISS index, semantic search, HDBSCAN clustering |
+| [Contributing](docs/contributing.md) | Development setup, testing, project structure |
+
+## License
+
+MIT