lore-kg 6.0.0__tar.gz

lore_kg-6.0.0/LICENSE

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

lore_kg-6.0.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: lore-kg
+Version: 6.0.0
+Summary: LORE: Local Institutional Memory & 5-Layer Knowledge Graph for Enterprise Codebases
+License: MIT
+Project-URL: Homepage, https://github.com/filippogabriele19/lore
+Project-URL: Repository, https://github.com/filippogabriele19/lore
+Project-URL: Issues, https://github.com/filippogabriele19/lore/issues
+Keywords: knowledge-graph,architecture,ai-code-memory,mcp,static-analysis,code-governance
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.7.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: libcst>=1.0.0
+Requires-Dist: networkx>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: tree-sitter-languages>=1.8.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: mcp>=1.0.0
+Dynamic: license-file
+
+# 🚀 LORE: The Local Institutional Memory Layer for AI Coding Agents
+
+**Stop AI from breaking your architecture. A 5-layer Knowledge Graph & Semantic Firewall for Cursor, Claude, and CI/CD.**
+
+[![PyPI Version](https://img.shields.io/pypi/v/lore-kg.svg)](https://pypi.org/project/lore-kg/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Model Context Protocol](https://img.shields.io/badge/MCP-Supported-green.svg)](https://modelcontextprotocol.io/)
+[![Build Status](https://github.com/filippogabriele19/lore/actions/workflows/test-and-lint.yml/badge.svg)](https://github.com/filippogabriele19/lore/actions)
+
+---
+
+## 📊 Empirical Performance (Django & LangChain Benchmark)
+
+LORE is backed by an empirical benchmark suite evaluated over **199 real commits** across the Django and LangChain repositories:
+
+| Metric | Performance | Impact |
+| :--- | :---: | :--- |
+| **High-Signal Precision** | **97.2%** [95% CI: 85.8%–99.5%] | When LORE issues a critical alert, **97.2% of the time it is a true regression**. |
+| **Clean PR False Positive Rate** | **1.0%** [95% CI: 0.2%–5.4%] | Near-zero alert fatigue on benign refactoring and documentation PRs. |
+| **Overall False Positive Reduction** | **88.7% Noise Reduction** | Precision-calibrated thresholds eliminate alert fatigue in production pipelines. |
+| **Symbol Co-Change Associations** | **816 Active Rules Mined** | Deep symbol-level association rules prevent missing coupled updates. |
+
+---
+
+## 💡 The Problem: AI Code Amnesia
+
+AI coding assistants (Cursor, Claude Code, Copilot, Devin) are incredibly good at writing syntax (the *what*), but they are completely blind to architectural intent and history (the *why*):
+- They refactor key endpoints without knowing the performance constraints or GDPR policies behind them.
+- They replace custom authentication schemes with standard ones, breaking compliance rules.
+- They lack context on implicit dependencies and files that always co-evolve (co-changes), leading to silent regressions.
+
+**When senior architects leave or team size grows, this knowledge debt leads to architectural decay.**
+
+---
+
+## 🎯 The Solution: LORE
+
+LORE reconstructs intent from your codebase evidence—mining git history, commit messages, PRs, Slack/GitHub webhooks, and Architectural Decision Records (ADRs) into a structured **5-layer Knowledge Graph**. 
+
+It serves as a **Semantic Firewall**, exposing this graph via **Model Context Protocol (MCP)**, **SARIF 2.1.0**, and a **GitHub Action** to guide AI agents and developers *before* they apply breaking changes.
+
+```mermaid
+graph TD
+    subgraph Evidence Sources
+        A1[Codebase & Git History]
+        A2["GitHub PRs & Issues (Webhooks & CLI)"]
+        A3["Slack Channel Chat logs (Webhooks & CLI)"]
+    end
+    
+    A1 & A2 & A3 -->|Ingestion & Mining| B[LORE Engine]
+    B -->|Builds| C[5-Layer Knowledge Graph]
+    
+    subgraph Knowledge Graph Layers
+        C1[L1: Structural AST Symbols (Py, Go, TS)]
+        C2[L2: Semantic Vector Store sqlite-vec]
+        C3[L3: Historical Co-changes & Fragility Scores]
+        C4[L4: Decisional Links to ADRs & PRs]
+        C5[L5: Institutional Policy & Boundary Rules]
+    end
+    
+    C --> C1 & C2 & C3 & C4 & C5
+    C -->|Exposes Context| D[Model Context Protocol Server]
+    C -->|Validates Diff| E[LORE Guardian & SARIF Output]
+    
+    D -->|Guide Agent| F[Cursor / Claude Desktop / Claude Code]
+    E -->|Block Breaking PR| G[Pull Request Gatekeeper]
+```
+
+---
+
+## ⚡ Quick Start: Experience LORE in 60 Seconds
+
+### 1. Install LORE
+```bash
+pip install lore-kg
+```
+
+### 2. Initialize Workspace & Index Codebase
+Set your LLM API key (e.g. Anthropic, OpenAI, DeepSeek, or OpenRouter):
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+```
+
+Then, run the bootstrap helper inside your repository to scan files and build your Knowledge Graph:
+```bash
+lore init .
+```
+
+### 3. Run Architectural Audit in CI/CD or PRs
+Audit local modifications or PR commit ranges:
+```bash
+lore gh-check --commit-range "origin/main...HEAD" --format sarif --fail-on critical
+```
+
+### 4. Query the Knowledge Graph
+Ask questions about why the codebase is structured the way it is:
+```bash
+lore query "Why did we replace JWT with opaque tokens in auth.py?"
+```
+
+---
+
+## ⚖️ What Makes LORE Different?
+
+| Feature | Standard RAG / Code Search | AI IDE / Assistants | LORE |
+| :--- | :---: | :---: | :---: |
+| **AST Symbol Resolution** | ❌ (reads text chunks) | ❌ (raw file contents) | **✅ L1-L2 AST Graph (Py, Go, TS)** |
+| **Understand *Why* (ADRs)** | ❌ | ❌ | **✅ L4 Scoped Decisional Links** |
+| **Symbol Co-Change Rules** | ❌ | ❌ | **✅ 800+ Mined Association Rules** |
+| **Boundary Condition Miner** | ❌ | ❌ | **✅ Operator Weakening Alerts (`>` $\rightarrow$ `>=`)** |
+| **Inter-Procedural Taint Graph**| ❌ | ❌ | **✅ Source-to-Sink Dataflow Tracing** |
+| **AI Compliance Gate** | ❌ | ❌ | **✅ Pre-commit / SARIF CI/CD Gate** |
+| **Offline Vector Search** | ❌ (cloud dependency) | ❌ | **✅ Local via `sqlite-vec` (C)** |
+
+---
+
+## 🛠️ CLI Command Overview
+
+| Command | Description |
+| :--- | :--- |
+| `lore init` | Initialize LORE workspace and index project files (bootstrap). |
+| `lore gh-check` | Run PR security & architecture audit with `--format [markdown\|json\|sarif]` and `--fail-on`. |
+| `lore reindex` | Re-compute symbol fragility scores & co-changes across existing Knowledge Graphs. |
+| `lore dismiss` | Suppress a false positive LORE warning for a file or symbol persistent in SQLite. |
+| `lore query` | Query the Knowledge Graph for architectural questions (read-only). |
+| `lore adr` | Generate and index an Architectural Decision Record (ADR) to cure Amnesia. |
+| `lore mcp` | Start the Model Context Protocol (MCP) server for Cursor & Claude Desktop. |
+| `lore git-hook` | Install or uninstall LORE pre-commit git hooks. |
+
+---
+
+## 🛡️ GitHub Action & SARIF Integration
+
+Integrate LORE Guardian into your GitHub Code Scanning and Security tab via native SARIF 2.1.0 output:
+
+```yaml
+# .github/workflows/lore-audit.yml
+name: LORE Security & Architecture Guard
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lore-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for git mining
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install LORE
+        run: pip install lore-kg
+
+      - name: Run LORE Audit
+        run: lore gh-check --commit-range "origin/main...HEAD" --format sarif --fail-on critical > lore-results.sarif
+
+      - name: Upload SARIF report to GitHub Security Tab
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: lore-results.sarif
+```
+
+---
+
+## 📜 Contributing & License
+
+For development setup instructions, please read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+LORE is open-source software licensed under the [MIT License](LICENSE).

lore_kg-6.0.0/README.md

@@ -0,0 +1,176 @@
+# 🚀 LORE: The Local Institutional Memory Layer for AI Coding Agents
+
+**Stop AI from breaking your architecture. A 5-layer Knowledge Graph & Semantic Firewall for Cursor, Claude, and CI/CD.**
+
+[![PyPI Version](https://img.shields.io/pypi/v/lore-kg.svg)](https://pypi.org/project/lore-kg/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Model Context Protocol](https://img.shields.io/badge/MCP-Supported-green.svg)](https://modelcontextprotocol.io/)
+[![Build Status](https://github.com/filippogabriele19/lore/actions/workflows/test-and-lint.yml/badge.svg)](https://github.com/filippogabriele19/lore/actions)
+
+---
+
+## 📊 Empirical Performance (Django & LangChain Benchmark)
+
+LORE is backed by an empirical benchmark suite evaluated over **199 real commits** across the Django and LangChain repositories:
+
+| Metric | Performance | Impact |
+| :--- | :---: | :--- |
+| **High-Signal Precision** | **97.2%** [95% CI: 85.8%–99.5%] | When LORE issues a critical alert, **97.2% of the time it is a true regression**. |
+| **Clean PR False Positive Rate** | **1.0%** [95% CI: 0.2%–5.4%] | Near-zero alert fatigue on benign refactoring and documentation PRs. |
+| **Overall False Positive Reduction** | **88.7% Noise Reduction** | Precision-calibrated thresholds eliminate alert fatigue in production pipelines. |
+| **Symbol Co-Change Associations** | **816 Active Rules Mined** | Deep symbol-level association rules prevent missing coupled updates. |
+
+---
+
+## 💡 The Problem: AI Code Amnesia
+
+AI coding assistants (Cursor, Claude Code, Copilot, Devin) are incredibly good at writing syntax (the *what*), but they are completely blind to architectural intent and history (the *why*):
+- They refactor key endpoints without knowing the performance constraints or GDPR policies behind them.
+- They replace custom authentication schemes with standard ones, breaking compliance rules.
+- They lack context on implicit dependencies and files that always co-evolve (co-changes), leading to silent regressions.
+
+**When senior architects leave or team size grows, this knowledge debt leads to architectural decay.**
+
+---
+
+## 🎯 The Solution: LORE
+
+LORE reconstructs intent from your codebase evidence—mining git history, commit messages, PRs, Slack/GitHub webhooks, and Architectural Decision Records (ADRs) into a structured **5-layer Knowledge Graph**. 
+
+It serves as a **Semantic Firewall**, exposing this graph via **Model Context Protocol (MCP)**, **SARIF 2.1.0**, and a **GitHub Action** to guide AI agents and developers *before* they apply breaking changes.
+
+```mermaid
+graph TD
+    subgraph Evidence Sources
+        A1[Codebase & Git History]
+        A2["GitHub PRs & Issues (Webhooks & CLI)"]
+        A3["Slack Channel Chat logs (Webhooks & CLI)"]
+    end
+    
+    A1 & A2 & A3 -->|Ingestion & Mining| B[LORE Engine]
+    B -->|Builds| C[5-Layer Knowledge Graph]
+    
+    subgraph Knowledge Graph Layers
+        C1[L1: Structural AST Symbols (Py, Go, TS)]
+        C2[L2: Semantic Vector Store sqlite-vec]
+        C3[L3: Historical Co-changes & Fragility Scores]
+        C4[L4: Decisional Links to ADRs & PRs]
+        C5[L5: Institutional Policy & Boundary Rules]
+    end
+    
+    C --> C1 & C2 & C3 & C4 & C5
+    C -->|Exposes Context| D[Model Context Protocol Server]
+    C -->|Validates Diff| E[LORE Guardian & SARIF Output]
+    
+    D -->|Guide Agent| F[Cursor / Claude Desktop / Claude Code]
+    E -->|Block Breaking PR| G[Pull Request Gatekeeper]
+```
+
+---
+
+## ⚡ Quick Start: Experience LORE in 60 Seconds
+
+### 1. Install LORE
+```bash
+pip install lore-kg
+```
+
+### 2. Initialize Workspace & Index Codebase
+Set your LLM API key (e.g. Anthropic, OpenAI, DeepSeek, or OpenRouter):
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+```
+
+Then, run the bootstrap helper inside your repository to scan files and build your Knowledge Graph:
+```bash
+lore init .
+```
+
+### 3. Run Architectural Audit in CI/CD or PRs
+Audit local modifications or PR commit ranges:
+```bash
+lore gh-check --commit-range "origin/main...HEAD" --format sarif --fail-on critical
+```
+
+### 4. Query the Knowledge Graph
+Ask questions about why the codebase is structured the way it is:
+```bash
+lore query "Why did we replace JWT with opaque tokens in auth.py?"
+```
+
+---
+
+## ⚖️ What Makes LORE Different?
+
+| Feature | Standard RAG / Code Search | AI IDE / Assistants | LORE |
+| :--- | :---: | :---: | :---: |
+| **AST Symbol Resolution** | ❌ (reads text chunks) | ❌ (raw file contents) | **✅ L1-L2 AST Graph (Py, Go, TS)** |
+| **Understand *Why* (ADRs)** | ❌ | ❌ | **✅ L4 Scoped Decisional Links** |
+| **Symbol Co-Change Rules** | ❌ | ❌ | **✅ 800+ Mined Association Rules** |
+| **Boundary Condition Miner** | ❌ | ❌ | **✅ Operator Weakening Alerts (`>` $\rightarrow$ `>=`)** |
+| **Inter-Procedural Taint Graph**| ❌ | ❌ | **✅ Source-to-Sink Dataflow Tracing** |
+| **AI Compliance Gate** | ❌ | ❌ | **✅ Pre-commit / SARIF CI/CD Gate** |
+| **Offline Vector Search** | ❌ (cloud dependency) | ❌ | **✅ Local via `sqlite-vec` (C)** |
+
+---
+
+## 🛠️ CLI Command Overview
+
+| Command | Description |
+| :--- | :--- |
+| `lore init` | Initialize LORE workspace and index project files (bootstrap). |
+| `lore gh-check` | Run PR security & architecture audit with `--format [markdown\|json\|sarif]` and `--fail-on`. |
+| `lore reindex` | Re-compute symbol fragility scores & co-changes across existing Knowledge Graphs. |
+| `lore dismiss` | Suppress a false positive LORE warning for a file or symbol persistent in SQLite. |
+| `lore query` | Query the Knowledge Graph for architectural questions (read-only). |
+| `lore adr` | Generate and index an Architectural Decision Record (ADR) to cure Amnesia. |
+| `lore mcp` | Start the Model Context Protocol (MCP) server for Cursor & Claude Desktop. |
+| `lore git-hook` | Install or uninstall LORE pre-commit git hooks. |
+
+---
+
+## 🛡️ GitHub Action & SARIF Integration
+
+Integrate LORE Guardian into your GitHub Code Scanning and Security tab via native SARIF 2.1.0 output:
+
+```yaml
+# .github/workflows/lore-audit.yml
+name: LORE Security & Architecture Guard
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lore-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for git mining
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install LORE
+        run: pip install lore-kg
+
+      - name: Run LORE Audit
+        run: lore gh-check --commit-range "origin/main...HEAD" --format sarif --fail-on critical > lore-results.sarif
+
+      - name: Upload SARIF report to GitHub Security Tab
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: lore-results.sarif
+```
+
+---
+
+## 📜 Contributing & License
+
+For development setup instructions, please read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+LORE is open-source software licensed under the [MIT License](LICENSE).

lore_kg-6.0.0/cli/adr.py

@@ -0,0 +1,80 @@
+import os, sys, argparse, json
+from pathlib import Path
+from cli.shared import console, DEFAULT_PROJECT, _get_db_path
+
+def _main_adr(argv: list[str]) -> None:
+    """adr mode — generate a draft ADR to cure institutional amnesia and index it in the KG."""
+    import argparse
+    parser = argparse.ArgumentParser(
+        prog="lore adr",
+        description="Generate and index an Architectural Decision Record (ADR) to cure Amnesia",
+    )
+    parser.add_argument("--project", default=DEFAULT_PROJECT,
+                        help=f"Path to project root (default: {DEFAULT_PROJECT})")
+    parser.add_argument("--file", required=True,
+                        help="Relative file path associated with the decision")
+    parser.add_argument("--title", required=True,
+                        help="Short title/description of the architectural invariant")
+    parser.add_argument("--symbol", default=None,
+                        help="Optional symbol name (class/function) to bind the decision to")
+    args = parser.parse_args(argv)
+
+    project_root = Path(args.project)
+    if not project_root.exists():
+        console.print(f"[error]Project path not found: {project_root}[/]")
+        sys.exit(1)
+
+    db_path = _get_db_path(project_root)
+    if not db_path.exists():
+        console.print(f"[error]✖ Database not found under {project_root}[/]")
+        sys.exit(1)
+
+    # 1. Write the markdown ADR file
+    adr_dir = project_root / ".lore" / "adr"
+    adr_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Generate unique ID/filename
+    from datetime import datetime as _dt
+    import random
+    ts = _dt.now().strftime("%Y%m%d_%H%M%S")
+    rand_id = random.randint(1000, 9999)
+    adr_filename = f"adr_{ts}_{rand_id}.md"
+    adr_path = adr_dir / adr_filename
+
+    adr_content = f"""# ADR: {args.title}
+
+## Metadata
+- **Date**: {_dt.now().strftime("%Y-%m-%d")}
+- **Target File**: {args.file}
+- **Target Symbol**: {args.symbol or "File-level Invariant"}
+- **Status**: Accepted
+
+## Context
+Describe the context and the problem we are solving, including any security requirements or invariants (e.g. inputs must be validated, credentials must come from environment).
+
+## Decision
+Describe the decision and the design rules. What must developers do or avoid doing in this subsystem?
+
+## Consequences
+What are the consequences of this decision? What are the tradeoffs?
+"""
+    adr_path.write_text(adr_content, encoding="utf-8")
+    console.print(f"[success]✔ ADR file generated successfully:[/] [underline info]{adr_path}[/]")
+
+    # 2. Register it in decision_links table in the database
+    from core.symbol_db import SymbolDB
+    db = SymbolDB(db_path)
+    
+    try:
+        # Try to find symbol ID if symbol is specified
+        symbol_name = args.symbol if args.symbol else args.file.replace("\\", "/").split("/")[-1]
+        
+        db.register_decision_link(symbol_name, "adr", f".lore/adr/{adr_filename}", 1.0, args.title)
+        db.commit()
+    finally:
+        db.close()
+
+    
+    console.print(f"[success]✔ Decision Link registered in the Knowledge Graph for symbol [bold cyan]{symbol_name}[/]. Amnesia cured![/]\n")
+
+