codebase-cortex 0.1.0__py3-none-any.whl

codebase_cortex/utils/section_parser.py

@@ -0,0 +1,139 @@
+"""Markdown section parser for section-level page updates."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class Section:
+    """A section of a markdown document."""
+
+    heading: str  # Full heading line e.g. "## API Endpoints" (empty for preamble)
+    level: int  # Number of # symbols (0 for preamble)
+    content: str  # Content between this heading and the next
+
+    @property
+    def full_text(self) -> str:
+        """Reconstruct the section as it appears in the document."""
+        if self.heading and self.content:
+            return f"{self.heading}\n{self.content}"
+        return self.heading or self.content
+
+
+def parse_sections(markdown: str) -> list[Section]:
+    """Parse markdown into a flat list of sections split by headings.
+
+    Each section contains the heading line and all content until the next heading.
+    Content before the first heading becomes a preamble section with level 0.
+    """
+    if not markdown or not markdown.strip():
+        return []
+
+    lines = markdown.split("\n")
+    sections: list[Section] = []
+    current_heading = ""
+    current_level = 0
+    buffer: list[str] = []
+
+    for line in lines:
+        match = re.match(r"^(#{1,6})\s+", line)
+        if match:
+            # Flush previous section
+            content = "\n".join(buffer).strip()
+            if current_heading or content:
+                sections.append(Section(
+                    heading=current_heading,
+                    level=current_level,
+                    content=content,
+                ))
+            current_heading = line
+            current_level = len(match.group(1))
+            buffer = []
+        else:
+            buffer.append(line)
+
+    # Flush last section
+    content = "\n".join(buffer).strip()
+    if current_heading or content:
+        sections.append(Section(
+            heading=current_heading,
+            level=current_level,
+            content=content,
+        ))
+
+    return sections
+
+
+def normalize_heading(heading: str) -> str:
+    """Normalize a heading for fuzzy comparison.
+
+    Strips # symbols, extra whitespace, and lowercases.
+    """
+    stripped = re.sub(r"^#+\s*", "", heading).strip()
+    return stripped.lower()
+
+
+def merge_sections(
+    existing_sections: list[Section],
+    section_updates: list[dict],
+) -> str:
+    """Merge section-level updates into existing page content.
+
+    For each update:
+    - action "update": replaces the matching section's content (heading preserved)
+    - action "create": appends as a new section at the end
+
+    If an "update" heading doesn't match any existing section, it's appended
+    as a new section (graceful fallback).
+
+    Returns the full reconstructed page content.
+    """
+    update_map: dict[str, dict] = {}
+    new_sections: list[dict] = []
+
+    for update in section_updates:
+        action = update.get("action", "update")
+        if action == "create":
+            new_sections.append(update)
+        else:
+            norm = normalize_heading(update.get("heading", ""))
+            if norm:
+                update_map[norm] = update
+
+    result_parts: list[str] = []
+    matched: set[str] = set()
+
+    for section in existing_sections:
+        norm = normalize_heading(section.heading) if section.heading else ""
+        if norm and norm in update_map:
+            update = update_map[norm]
+            matched.add(norm)
+            new_content = update.get("content", "").strip()
+            # Keep original heading format, replace content
+            if section.heading:
+                result_parts.append(f"{section.heading}\n{new_content}")
+            else:
+                result_parts.append(new_content)
+        else:
+            result_parts.append(section.full_text)
+
+    # Append unmatched "update" entries as new sections (heading not found)
+    for norm, update in update_map.items():
+        if norm not in matched:
+            heading = update.get("heading", "")
+            content = update.get("content", "").strip()
+            if heading and content:
+                result_parts.append(f"{heading}\n{content}")
+
+    # Append explicitly new sections
+    for new_sec in new_sections:
+        heading = new_sec.get("heading", "")
+        content = new_sec.get("content", "").strip()
+        if heading and content:
+            result_parts.append(f"{heading}\n{content}")
+        elif content:
+            result_parts.append(content)
+
+    return "\n\n".join(part for part in result_parts if part.strip())

codebase_cortex-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,37 @@
+codebase_cortex/__init__.py,sha256=hKMkN2o22KHG_Z-Y9AaJPaMkEZs-YF1opIXlUzxNpw4,112
+codebase_cortex/cli.py,sha256=BU0HPfQ3KS6tVFr_WLGOq5xa3rOTVrHBZjnXUdO77B0,31640
+codebase_cortex/config.py,sha256=zQIlCrXRTGf0rW26ngfweNKpvSIJPZ9GpmknYXcrct8,4489
+codebase_cortex/graph.py,sha256=wsW0OkYscKbecO-TmG7RdQwNxAbUM92v_4uqiSDf5p4,3491
+codebase_cortex/mcp_client.py,sha256=jNzGUBXb0OYoA11yv72ho14LU2LzCudZIQuJkpos1m8,3004
+codebase_cortex/state.py,sha256=4BnASFMZU2oEAMp-k4qtmgP3SSpUUdG6irEYg4b54LI,1700
+codebase_cortex/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebase_cortex/agents/base.py,sha256=skj0FHxKvjFPzHjy7XUr3RJe7d2OqEPjOC5nh-WBKc8,2383
+codebase_cortex/agents/code_analyzer.py,sha256=f_8kzftye4xOrvSq0B5s5oO-r1WgahV5kkcnf6ljULE,4537
+codebase_cortex/agents/doc_writer.py,sha256=ohRf_R80pMocak3hkK1GSmz42-AwXYY-H4p5pos2Qhg,14895
+codebase_cortex/agents/semantic_finder.py,sha256=uxoBu94evAqiUHEyEGQbZP3ICKMBdIeZZYEseDf9Tis,2248
+codebase_cortex/agents/sprint_reporter.py,sha256=t3nyrJnjhZEDXrJwpK--7NbpNSs840V_gw2FL1p070A,5852
+codebase_cortex/agents/task_creator.py,sha256=NGfC4Zg37GUx4sNsW6MZK7kUdTLFs-C3q2D9c7xBMNg,5336
+codebase_cortex/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebase_cortex/auth/callback_server.py,sha256=E15ivNx1nWpt7RY9gsMaaiDKqlCg5HDofPFeugcVEq0,2694
+codebase_cortex/auth/oauth.py,sha256=CPD94odyS0YiXwjaxbHdXKI9jI3vpw1G_1GoW59ra4A,5257
+codebase_cortex/auth/token_store.py,sha256=a4X99UccYbkd_q3yQhRUjGJRL6KWp5ydO74e3pFaEDo,2524
+codebase_cortex/embeddings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebase_cortex/embeddings/clustering.py,sha256=oTAU71DCHEcs44cdUmjm4Ag6uruH8vgbXVoZp1kbHBQ,4496
+codebase_cortex/embeddings/indexer.py,sha256=4zxLKMy1Y4vz4vxsrJ8lNDK8SCZCEbiq4YXtwAkij_s,7012
+codebase_cortex/embeddings/store.py,sha256=ZHn-Uo2f14WkcRFBD4QIQi9vJLd1M81NMp6oQMxflOc,3953
+codebase_cortex/git/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebase_cortex/git/diff_parser.py,sha256=kujnB1dcW0L-eL_KnzrpC4-I-Rl8pHvwxD8201q2Saw,5487
+codebase_cortex/git/github_client.py,sha256=_5yDz4dgwtQTss6qBlW0_7Py_RZixRNeJVd_WcFrN3c,1279
+codebase_cortex/notion/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebase_cortex/notion/bootstrap.py,sha256=2L0l90IEej272cfHgb4MrsYNc2PvDNfbqWLloCSs5H4,10616
+codebase_cortex/notion/page_cache.py,sha256=JSgf51gWwnCUbNLwNRPq1sr1cCDhPDLBljjXFGqXd7g,3507
+codebase_cortex/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebase_cortex/utils/json_parsing.py,sha256=zDruntjXKwGUrbHe5kYmaMj9ZaT3WLXlqlSmpjiKePQ,1678
+codebase_cortex/utils/logging.py,sha256=rSWZFXGtXY7Nz00onrankTaYQdhXBXIO7pwoDGBQKqM,1569
+codebase_cortex/utils/rate_limiter.py,sha256=e8ijgOJAiG2_EKprVrxG-6yPrcXcbKg0GDkCxiijt64,1665
+codebase_cortex/utils/section_parser.py,sha256=BUrXmbJUPGRGSaZ9_YyG91Hvq9-C6Z_XIaQWrQAiTWM,4496
+codebase_cortex-0.1.0.dist-info/METADATA,sha256=YG8MNvbPWMpay0zxIigaMjGmTq9R0XAsO5LV9Gn-moI,8236
+codebase_cortex-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+codebase_cortex-0.1.0.dist-info/entry_points.txt,sha256=KfBJoRID7C0JYztS5F6bbL7PGpXcdu1yiwKf1oJzzQk,93
+codebase_cortex-0.1.0.dist-info/licenses/LICENSE,sha256=qAL3B2b4WSnYV-A1VouD_sPw3PSzwBtVIKSCSil0lHs,1076
+codebase_cortex-0.1.0.dist-info/RECORD,,

codebase_cortex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codebase_cortex-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+codebase-cortex = codebase_cortex.cli:cli
+cortex = codebase_cortex.cli:cli

codebase_cortex-0.1.0.dist-info/licenses/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.