Metadata-Version: 2.4
Name: grid-intelligence
Version: 2.6.1
Summary: GRID - Geometric Resonance Intelligence Driver: A comprehensive framework for exploring complex systems through geometric resonance patterns, cognitive decision support, local-first AI, and event-driven agentic systems
Project-URL: Homepage, https://github.com/GRID-INTELLIGENCE/GRID
Project-URL: Repository, https://github.com/GRID-INTELLIGENCE/GRID
Project-URL: Issues, https://github.com/GRID-INTELLIGENCE/GRID/issues
Author-email: Irfan Kabir <irfankabir02@gmail.com>
License: MIT License
        
        Copyright (c) 2025-2026 Irfan Kabir
        
        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.
License-File: LICENSE
Keywords: agentic,ai,cognitive-architecture,ddd,event-driven,geometric-resonance,machine-learning,rag
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: <3.14,>=3.13
Requires-Dist: aio-pika>=9.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: annotated-doc>=0.0.2
Requires-Dist: annotated-types>=0.6.0
Requires-Dist: anyio>=4.0.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: bcrypt>=4.1.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: celery>=5.3.0
Requires-Dist: chromadb>=1.4.1
Requires-Dist: click>=8.0.0
Requires-Dist: databricks-sdk>=0.40.0
Requires-Dist: databricks-sql-connector>=4.2.4
Requires-Dist: detect-secrets>=1.4.0
Requires-Dist: email-validator>=2.1.0.post1
Requires-Dist: fastapi>=0.104.0
Requires-Dist: grid-safety>=1.0.1
Requires-Dist: httpx>=0.25.0
Requires-Dist: huggingface-hub>=1.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markupsafe>=2.0.0
Requires-Dist: mcp[cli]>=1.25.0
Requires-Dist: nbformat>=5.9.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: ollama>=0.6.1
Requires-Dist: opentelemetry-api>=1.21.0
Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
Requires-Dist: opentelemetry-exporter-otlp>=0.42.0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.42b0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.42b0
Requires-Dist: opentelemetry-instrumentation-logging>=0.42b0
Requires-Dist: opentelemetry-instrumentation-requests>=0.42b0
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.42b0
Requires-Dist: opentelemetry-sdk>=1.21.0
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: prometheus-fastapi-instrumentator>=7.0.0
Requires-Dist: pydantic-core>=2.14.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.4.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Requires-Dist: pypdf2>=3.0.0
Requires-Dist: python-docx>=0.8.11
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: redis>=5.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: schedule>=1.2.2
Requires-Dist: scikit-learn>=1.5.0
Requires-Dist: sentence-transformers>=5.2.0
Requires-Dist: setuptools<81
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: stripe>=14.0.1
Requires-Dist: structlog>=23.1.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: typing-extensions>=4.5.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: ai
Requires-Dist: mistralai>=0.1.0; extra == 'ai'
Requires-Dist: openai>=1.0.0; extra == 'ai'
Description-Content-Type: text/markdown

# GRID - Geometric Resonance Intelligence Driver

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/grid-intelligence.svg)](https://pypi.org/project/grid-intelligence/)
[![Tests](https://github.com/GRID-INTELLIGENCE/GRID/actions/workflows/minimal-ci.yml/badge.svg?branch=main)](https://github.com/GRID-INTELLIGENCE/GRID/actions/workflows/minimal-ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
[![Linter: Ruff](https://img.shields.io/badge/linter-ruff-261230.svg)](https://github.com/astral-sh/ruff)

[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/GRID-INTELLIGENCE/GRID/pulls)
[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/GRID-INTELLIGENCE/GRID/graphs/commit-activity)
[![Made with Love](https://img.shields.io/badge/Made%20with-❤️-red.svg)](https://github.com/GRID-INTELLIGENCE/GRID)

</div>

<div align="center">

### 🎯 Local-First AI · 🔒 Privacy-First · ⚡ Production-Ready

</div>

## Quick Install

```bash
pip install grid-intelligence
grid --help
```

For contributor/development setup, see [INSTALLATION.md](docs/INSTALLATION.md).

## 🎬 Interactive Demo

<div align="center">

### 🌐 **[Try Live Demo →](https://grid-intelligence.netlify.app)**

[![GRID Landing Page](https://img.shields.io/badge/🌐_Live_Demo-Visit_Now-00D9FF?style=for-the-badge&logo=netlify&logoColor=white)](https://grid-intelligence.netlify.app)
[![Deployment](https://img.shields.io/badge/Deployment-Active-success?style=for-the-badge&logo=vercel)](https://grid-intelligence.netlify.app)

</div>

<details>
<summary><b>📺 Watch the Terminal Demo</b> (Click to expand)</summary>

<br>

The landing page features an **interactive terminal simulation** that demonstrates GRID's code analysis capabilities in real-time. Here's what you'll see:

```bash
$ grid analyze src/

🔍 Analyzing codebase structure...
✓ Found 142 Python files
✓ Detected 89 classes, 437 functions
✓ Mapped 12 core modules

📊 Complexity Analysis:
  • Cyclomatic complexity: 8.2 avg (healthy)
  • Maintainability index: 76/100 (good)
  • Code duplication: 3.1% (low)

🧠 Pattern Recognition:
  • Flow patterns: Event-driven architecture (15 events)
  • Spatial patterns: Layered DDD structure (4 layers)
  • Cause patterns: 23 dependency chains detected

💡 Recommendations:
  1. Extract shared logic in auth module → reduce duplication by 40%
  2. Consider breaking down UserService (complexity: 12) → target: <10
  3. Add integration tests for payment flows → coverage gap detected

✨ Analysis complete in 2.3s
```

<div align="center">

**[→ See it in action on the live site](https://grid-intelligence.netlify.app#demo)**

</div>

</details>

<details>
<summary><b>✨ Landing Page Features</b> (Click to expand)</summary>

<br>

### What's Inside

- 🎯 **Interactive Terminal** - Real-time code analysis simulation with typing effects
- 📊 **Visual Insights** - Pattern recognition and complexity metrics display
- 🤖 **AI-Powered** - Local-first intelligence with Ollama (no external APIs)
- 🔒 **Privacy-First** - Your code never leaves your machine
- 🎨 **Dark Mode** - Beautiful dark/light theme toggle
- 📱 **Responsive** - Fully mobile-optimized design
- ⚡ **Fast** - Performance-optimized with lazy loading

### Sections

- **Hero** - Eye-catching introduction with metrics (2.3M+ parameters, 500k+ stars)
- **Features** - Comprehensive overview of capabilities
- **Pricing** - Beta signup and tier comparison
- **About** - Project evolution story and philosophy
- **FAQ** - Simplified, accessible answers to common questions

<div align="center">

**Located in:** `landing/` directory | **Deployed on:** Netlify

</div>

</details>

---

## 📊 Project Stats

<div align="center">

| 🎯 Metric | 📈 Value | 🎯 Metric | 📈 Value |
|-----------|----------|-----------|----------|
| **Python Version** | 3.13+ | **Tests Passing** | 438+ ✅ |
| **Code Coverage** | ≥80% | **Architecture** | DDD + Event-Driven |
| **Lint Errors** | 0 (ruff clean) | **RAG Precision** | +33-40% |
| **Security** | Production-Ready | **Package Manager** | UV |

</div>

<div align="center">

### 🚀 Quick Stats

![Lines of Code](https://img.shields.io/badge/Lines%20of%20Code-50k%2B-blue?style=flat-square)
![Files](https://img.shields.io/badge/Files-748-green?style=flat-square)
![Tests](https://img.shields.io/badge/Tests-438%2B-success?style=flat-square)
![Lint](https://img.shields.io/badge/Lint-0%20errors-brightgreen?style=flat-square)

</div>

---

## Overview

GRID (Geometric Resonance Intelligence Driver) is a comprehensive framework for exploring and understanding complex systems through:

- **Geometric Resonance Patterns**: Core intelligence engine with 9 cognition patterns (Flow, Spatial, Rhythm, Color, Repetition, Deviation, Cause, Time, Combination)
- **Cognitive Decision Support**: Light of the Seven cognitive architecture for bounded rationality and human-centered AI
- **Local-First RAG**: Retrieval-Augmented Generation with ChromaDB + Ollama by default. **Optional / Cloud Hybrid:** External providers (OpenAI, Anthropic, Gemini) are supported only when explicitly configured via `RAG_LLM_MODE=external` and the corresponding API keys; see [Optional: External LLM / Cloud Hybrid](#optional-external-llm--cloud-hybrid) below. Default remains local; no data leaves your machine unless you opt in.
- **Intelligent Skills Ecosystem**: Self-organizing framework with automated discovery, persistent intelligence, and performance guarding (Phases 1-4)
- **Event-Driven Agentic System**: Complete case management workflow with continuous learning
- **Domain-Driven Design**: Professional architectural patterns with service layer decoupling

## 🚀 What's New (February 2026)

### v2.5.0 — Environmental Intelligence & Round Table

- ✅ **GRID Environmental Intelligence** — Homeostatic middleware using Le Chatelier's Principle to maintain conversational balance across three dimensions (Practical, Legal, Psychological)
- ✅ **Round Table Facilitator** — 4-phase multi-agent discussion orchestrator (open → discuss → synthesize → close) with environment-aware LLM parameter adjustment
- ✅ **EnvironmentalLLMProxy** — Wraps any `BaseLLMProvider` with dynamic parameter adjustment based on conversational equilibrium
- ✅ **RoundTablePage** — Frontend page for initiating and visualizing round table discussions
- ✅ **60 New Tests** — 43 environment tests (9 classes) + 17 round table facilitator tests; all passing

### v2.4.1 — Consolidation & Snapshot Integrity

- ✅ **Main Consolidation Completed** — `main` remains the authoritative baseline after branch audit and merge mitigation review
- ✅ **Unsafe Branch Mitigated** — `copilot-worktree-2026-02-17T11-02-39` explicitly rejected and logged in `docs/decisions/DECISIONS.md`
- ✅ **Snapshot Functionality Verified** — Snapshot capture tests validated for structural and landscape tracking flows
- ✅ **Async Skill Runtime Stability** — sync wrappers now safely resolve async handlers across running and non-running event loop contexts
- ✅ **Test Collection Hardening** — RAG contract tests now skip cleanly when optional `chromadb` import fails at environment level

### v2.4.0 — Full Lint Remediation & Cleanup

- ✅ **664→0 Lint Errors** — Complete ruff remediation across 251 files; codebase is lint-clean
- ✅ **StrEnum Modernization** — 122 classes converted to PEP 695 `StrEnum` inheritance
- ✅ **PERF401 Optimization** — 85 manual list constructions converted to comprehensions/`extend()`
- ✅ **Repository Cleanup** — Removed tracked artifacts (bandit reports, telemetry dumps, tmp scripts)
- ✅ **Documentation Refresh** — CHANGELOG.md, updated METADATA.md, validation report addendum
- ✅ **Version Bump** — 2.3.0 → 2.4.0

### v2.3.0 — CI & Code Quality Hardening

- ✅ **CI Pipeline Fixes** — Re-enabled push triggers, fixed test collection (`test_ollama.py`, `test_honor_decay_edge_cases.py`)
- ✅ **Formatter Consolidation** — Replaced Black with Ruff format in CI; single toolchain for linting + formatting
- ✅ **Expanded Ruff Rules** — Added S (security), SIM (simplify), C4 (comprehensions), PERF (performance) rules
- ✅ **Blocking I/O Fix** — Fixed critical async function in `agentic_system.py`
- ✅ **GUARDIAN Engine Hardening** — ReDoS guard, LIMITATIONS headers (Trust Layer Rule 3.2), encapsulation fixes, priority sort bug fix
- ✅ **Pytest Timeout** — Default 300s timeout prevents CI hangs
- ✅ **CI Matrix Aligned** — Test matrix matches `requires-python >=3.13`

### January 2026

### Major Enhancements:

- ✅ **Authentication & Security** - Production credential validation with bcrypt, JWT token revocation list, account lockout protection
- ✅ **Billing & Usage** - Tier-based subscription management with automatic overage calculation
- ✅ **Security Hardening** - Comprehensive path traversal protection and validation
- ✅ **Advanced RAG System** - 4-phase optimization with semantic chunking, hybrid search, cross-encoder reranking
- ✅ **Enhanced Testing** - 283+ tests passing (100% core pass rate) with 15/15 Unified Fabric cases
- ✅ **Windows Compatibility** - Fixed pre-commit hooks and cross-platform path handling
- ✅ **Performance Monitoring** - Real-time system metrics and optimization
- ✅ **Dynamic Unified Fabric** - Event-driven architecture with distributed AI Safety across E:/
- ✅ **Databricks Scaffold** - Native Coinbase analytics pipeline architecture

### New Capabilities:

- **Automatic Overage Billing**: Usage-based charges when exceeding tier limits (relationship analysis, entity extraction)
- **Path Traversal Protection**: Robust security validation for all file operations
- **Semantic Chunking**: Context-aware document splitting for better RAG coherence
- **Hybrid Search**: BM25 + Vector fusion for improved recall and precision
- **Cross-Encoder Reranking**: 33-40% precision improvement with ms-marco-MiniLM-L6-v2
- **Evaluation Metrics**: Automated Context Relevance scoring and quality tracking
- **Distributed AI Safety**: `AISafetyBridge` for cross-project safety validation (wellness_studio → E:/)
- **Automatic Revenue Pipeline**: End-to-end signal-to-execution flow with multi-system auditing

---

## 📖 About GRID

<div align="center">

### **Built with care, not just code**

</div>

<details open>
<summary><b>🌟 The Story Behind GRID</b></summary>

<br>

### How It Started

GRID began in **late November 2025** with a simple commit: *"finance & science."* The first files were experiments—blank templates, empty idea journals. Someone figuring things out, not sure where it was going.

By early December, something shifted. A journal entry titled **"The Art of Detangling"** described discovering that the UI was being imported everywhere—*"a classic architectural sin."* That's when it stopped being just code and started becoming a **System**.

### What We Believe

Most AI tools pretend to know everything. We built GRID to be honest about what it doesn't know. There's a state in our pattern engine called **"MIST"**—for when the system detects something important but can't explain it. The code comment says:

> *"High confidence that we DON'T know."*

We spent time studying **Carl Jung's psychology** to understand epistemic humility—the idea that admitting *"I don't know"* is sometimes the smartest answer. That thinking shaped everything we build.

### The "No Matter" Principle

Our core design principle:

> *When the environment is noisy or overwhelming, separate signal from noise, compress it into a structured core, and keep moving.*

That's not from a textbook. It's from dealing with chaos and figuring out how to work through it.

### Being Real

An independent reviewer gave us a **9.2/10 for work ethics**, noting:

> *"Honest acknowledgment of remaining failures. Clear distinction between what was fixed vs what needs work."*

We're not perfect—early on, 29 tests were still failing. But we documented every fix, reported actual numbers instead of rounding up, and never claimed something worked until it actually did.

### The Journey

```
Nov 2025 → First commit. Blank templates. Beginning.
Dec 2025 → Architecture cleanup. Security foundation. Domain-driven design.
Jan 2026 → Cognitive layer. RAG optimization (+33-40% precision). Production hardening.
Feb 2026 → 540+ files. 283+ tests. 100% core pass rate. Environmental Intelligence. Version 2.5+. Production-ready. ✨
```

<div align="center">

**GRID isn't a corporate project with twenty engineers. It's built by someone who cares about doing things right—principled, not perfect. And that difference matters.**

</div>

</details>

---

## Optional: External LLM / Cloud Hybrid

GRID is **local-first by default**: RAG uses Ollama and ChromaDB on your machine, and **no code or data is sent to external APIs** unless you explicitly opt in.

If you want to use cloud LLM providers for RAG (OpenAI, Anthropic, or Google Gemini), you can enable **optional external LLM** via environment variables:

| Variable | Purpose |
|----------|---------|
| `RAG_LLM_MODE=external` | Switch RAG from local (Ollama) to external API |
| `RAG_LLM_PROVIDER` | `openai`, `anthropic`, or `gemini` |
| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | Provider API key (required when using that provider) |

**Privacy:** When using external providers, prompts and responses are sent to the chosen provider. Use only when you accept that data flow. For maximum privacy, keep the default (`RAG_LLM_MODE` unset or `local`).

---

## ❓ Frequently Asked Questions

<details>
<summary><b>💡 What is GRID Analyzer?</b></summary>

<br>

GRID Analyzer is a **privacy-first, local-first tool** that helps you understand any codebase in minutes. It uses local AI models to analyze code, map relationships, and answer questions—**all without sending your code to external APIs**. Everything runs on your machine.

</details>

<details>
<summary><b>🤖 How is this different from GitHub Copilot?</b></summary>

<br>

**Copilot helps you *write* code. GRID helps you *understand* code.**

Copilot suggests next lines; GRID analyzes entire codebases, maps relationships, and answers questions about architecture and dependencies.

</details>

<details>
<summary><b>🔒 Does my code really stay local?</b></summary>

<br>

**Yes.** GRID runs entirely on your machine using local AI models.

- ✅ Zero network requests
- ✅ No API keys needed
- ✅ Your code never leaves your computer
- ✅ You can even run it offline

</details>

<details>
<summary><b>💻 What programming languages do you support?</b></summary>

<br>

**Supported:** Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, Ruby, PHP, C#

**Coming soon:** More languages based on community demand. The semantic analysis works across any language.

</details>

<details>
<summary><b>⚡ How fast is the analysis?</b></summary>

<br>

- **Initial indexing:** ~1-5 minutes for 1M lines of code
- **Subsequent queries:** Near-instant (under 1 second)
- **Incremental updates:** Fast (only reindex changed files)

</details>

<details>
<summary><b>💾 What are the system requirements?</b></summary>

<br>

**Minimum:** 8GB RAM, 2GB disk space
**Recommended:** 16GB RAM, SSD

**Platforms:** Windows, Mac (Intel/M1), Linux
**Requirements:** Python 3.13+

</details>

<details>
<summary><b>🎯 What makes GRID unique?</b></summary>

<br>

Five key differentiators:

1. **Local-first architecture** — Built from the ground up, not retrofitted
2. **9 Cognition Patterns** — Unique framework for understanding complex systems
3. **Cognitive decision support** — Adapts to your behavior
4. **Production-grade security** — 10+ security layers
5. **State-of-the-art RAG** — 33-40% better precision than standard search

</details>

<details>
<summary><b>🎨 What are GRID's 9 Cognition Patterns?</b></summary>

<br>

A unique framework for understanding complex systems:

| Pattern | Purpose |
|---------|---------|
| **Flow** | Data pipelines and processing flows |
| **Spatial** | Architecture and component layout |
| **Rhythm** | Timing and execution patterns |
| **Color** | Categorization and type systems |
| **Repetition** | Recurring patterns and structures |
| **Deviation** | Anomalies and exceptions |
| **Cause** | Relationships and dependencies |
| **Time** | Evolution and change history |
| **Combination** | Integration and emergence |

This framework is **unique to GRID**—no competitor has this cognitive architecture.

</details>

<details>
<summary><b>🧠 How does GRID adapt to my cognitive state?</b></summary>

<br>

GRID uses a **Coffee House Metaphor** for cognitive load management:

- ☕ **Espresso mode** — Focused (32-char chunks)
- ☕ **Americano mode** — Balanced (64-char chunks)
- 🧊 **Cold Brew mode** — Comprehensive (128-char chunks)

It automatically detects your cognitive load and adapts responses accordingly.

</details>

<details>
<summary><b>🏗️ What is GRID's architecture?</b></summary>

<br>

GRID follows a **layered, domain-driven architecture** with six layers:

```
Entry Points → Application → Domain Services → Core Intelligence → Infrastructure → Data
```

Unlike typical tools that operate at a single level, GRID implements **multiple interacting cognitive layers**—creating a model closer to human cognition than standard software architecture.

</details>

<details>
<summary><b>🔬 What research has GRID contributed?</b></summary>

<br>

Several novel discoveries:

1. **Temporal Resonance with Q Factor** — Temporal reasoning in RAG systems inspired by audio engineering
2. **Boundary Contracts** — OS-level safety with formal ownership transfer
3. **Adaptive Intelligence Framework** — 7-step learning cycle with 8.5/10 research merit rating

These are implemented in **production code**, not just papers.

</details>

<details>
<summary><b>🎯 Who is GRID for?</b></summary>

<br>

Four key segments:

1. **Regulated industries** — Healthcare, finance, government that can't use cloud AI tools
2. **Privacy-conscious developers** — Concerned about AI data usage
3. **Offline environments** — Air-gapped systems requiring offline operation
4. **Individual developers** — Priced out of enterprise tools but need professional-grade understanding

</details>

<details>
<summary><b>🛠️ What problems does GRID solve?</b></summary>

<br>

Three critical pain points:

1. **Productivity** — Developers spend 40% of their time understanding code; GRID reduces this to minutes
2. **Privacy/compliance** — Most AI tools require sending code to external APIs; GRID processes everything locally
3. **Semantic understanding** — Text search can't answer "why" or "how" questions; GRID uses semantic analysis to understand code structure

</details>

<details>
<summary><b>🎓 Is GRID's architecture original?</b></summary>

<br>

GRID is **neither a clone nor a standard implementation**. While it draws inspiration from established patterns (seL4, Fuchsia, Rust ownership, cognitive science), it synthesizes these into something distinctly its own.

The **9 Cognition Patterns framework** and **Geometric Resonance metaphor** are proprietary innovations.

GRID represents **thoughtful synthesis**—a custom definition that evolved organically through principled experimentation.

</details>

<details>
<summary><b>💬 How do I get support?</b></summary>

<br>

- **Free tier:** Community forums
- **Professional:** Email support (48h response)
- **Team:** Priority email (24h)
- **Enterprise:** Dedicated support (4h SLA) + success manager

</details>

<details>
<summary><b>💯 What if I'm not satisfied?</b></summary>

<br>

**30-day money-back guarantee.** No questions asked. Cancel anytime—no long-term contracts.

</details>

---

## Installation

**This repo uses [uv](https://docs.astral.sh/uv/) as the Python package manager.** Do not use `python -m venv` or `pip install` directly—use uv for all environment and package operations.

### Quick setup (one command)

```powershell
uv sync --group dev --group test   # Creates .venv, installs everything
```

uv automatically creates a `.venv/` directory next to `pyproject.toml`, pins Python 3.13 (from `.python-version`), and installs all runtime + dev + test dependencies from the lockfile.

### Running commands

```powershell
uv run pytest                      # Run tests
uv run ruff check .                # Lint
uv run python -m grid --help       # Run GRID CLI
```

Or activate the venv manually: `.\.venv\Scripts\Activate.ps1` (Windows) / `source .venv/bin/activate` (Unix).

### Managing dependencies

```powershell
uv add <package>                   # Add a runtime dependency
uv add --group dev <package>       # Add a dev-only dependency
uv lock                            # Regenerate uv.lock
uv sync                            # Sync .venv to match lockfile
```

> [!IMPORTANT]
> **Do not** run `pip install` inside `.venv`. Use `uv add` to add packages so they are tracked in `pyproject.toml` and `uv.lock`.

> [!NOTE]
> The `.venv/` folder is **disposable**—delete it and run `uv sync` to recreate from scratch at any time. It is never committed to git.

### Legacy setup (not recommended)

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .\.venv\Scripts\Activate.ps1
pip install -e .
```

## UV usage (per-repo)

See `docs/UV_USAGE.md` for full copy-paste commands.

## Key Components

### Core Intelligence

- **Circuits**: Constraint-based pathway lighting system
- **Physics**: Spacetime geometry framework for non-Euclidean grids
- **RAG**: Retrieval-Augmented Generation system (ChromaDB + Ollama)
- **Cognitive Layer**: Decision support, mental models, and navigation (Light of the Seven)
- **Resonance API**: Real-time activity processing with adaptive feedback

### New Systems (2026)

- **🔐 Authentication & Billing**: JWT-based auth with token revocation, tier-based subscriptions with usage tracking
- **🤖 Agentic System**: Event-driven case management with continuous learning, plus Environmental Intelligence (homeostatic LLM parameter tuning) and Round Table multi-agent facilitation
- **🏗️ DDD Architecture**: Domain-driven design with service layer decoupling
- **📁 Organized Structure**: Clean root directory with logical organization
- **🏗️ Unified Fabric**: High-performance async event bus and distributed safety layer

### Visualization & Tools

- **Visualization**: Interactive data visualization tools
- **Arena (The Chase)**: Simulation + referee lab with diagnostics CLI
- **Workspace**: MCP servers and development tools

## Project Structure (2026)

The project has been reorganized with a clean, maintainable structure:

### 📁 Root Directory (Essential Files Only)

```
e:\grid/
├── src/                    # All source code
├── tests/                  # Test suite
├── docs/                   # Core documentation
├── config/                 # Configuration files
├── scripts/                # Build and development scripts
├── tools/                  # Development tools
├── workspace/              # MCP workspace
├── landing/                # Landing page (HTML/CSS/JS)
└── pyproject.toml         # Project configuration
```

### 📁 New Organized Directories

```
├── dev/                    # Development files
│   ├── debug/             # Debug scripts
│   ├── patches/           # Patch files
│   ├── logs/              # Development logs
│   └── temp/              # Temporary files
├── reports/                # Reports and analysis
│   ├── analysis/          # Analysis reports
│   ├── integration/       # Integration test failures
│   ├── checkpoints/       # Project checkpoints
│   └── daily/             # Daily reports
└── docs-ext/              # Extended documentation
    ├── guides/            # Implementation guides
    └── workflows/         # Workflow documentation
```

### 📦 Source Code Structure

```
src/
├── grid/                   # Core intelligence package
│   ├── agentic/           # Event-driven agentic system + environmental intelligence
│   ├── context/           # User context management
│   ├── workflow/          # Workflow orchestration
│   └── io/                # Input/output handling
├── application/           # FastAPI applications
├── tools/                  # Development tools (RAG, utilities)
├── cognitive/              # Cognitive architecture
└── unified_fabric/         # Event-driven core & AI Safety bridge
```

## Skills + RAG (Quickstart)

**Local-First RAG System** (ChromaDB + Ollama - no external APIs):

```bash
# Query knowledge base
python -m tools.rag.cli query "How does pattern recognition work?"

# Index/rebuild documentation
python -m tools.rag.cli index docs/ --rebuild --curate

# List available skills (Auto-discovered)
python -m grid skills list

# Run a skill with JSON args (Performance-tracked)
python -m grid skills run transform.schema_map --args-json '{"text":"...", "target_schema":"resonance"}'
```

See [`docs/INTELLIGENT_SKILLS_SYSTEM.md`](docs/INTELLIGENT_SKILLS_SYSTEM.md) for details on the automated discovery and management layer.

### Resonance API

The Resonance API provides a "canvas flip" checkpoint for mid-process alignment:

```bash
# Start the server
python -m application.mothership.main

# Call the definitive endpoint
curl -X POST http://localhost:8080/api/v1/resonance/definitive \
  -H "Content-Type: application/json" \
  -d '{"query": "Where do these features connect?", "progress": 0.65}'

# Process activity with cognitive support
curl -X POST http://localhost:8080/api/v1/resonance/process \
  -H "Content-Type: application/json" \
  -d '{"query": "create a new service", "activity_type": "code"}'
```

### 🔐 Authentication & Billing (NEW)

Secure authentication and subscription management with usage tracking:

```bash
# Authenticate and get tokens
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass", "scopes": ["read", "write"]}'

# Validate token
curl http://localhost:8080/api/v1/auth/validate \
  -H "Authorization: Bearer <access_token>"

# Logout (revokes token)
curl -X POST http://localhost:8080/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"
```

**Features:**
- **Production Credential Validation**: bcrypt password hashing with PostgreSQL integration
- **JWT Token Management**: Access/refresh tokens with automatic expiration
- **Token Revocation List**: JWT blacklisting for secure logout
- **Account Protection**: Failed attempt tracking and automatic lockout
- **Usage Tracking**: Per-user resource consumption monitoring
- **Overage Calculation**: Automatic billing for usage beyond tier limits

### 🤖 Agentic System (NEW)

The Event-Driven Agentic System implements a receptionist-lawyer-client workflow for structured case processing:

```bash
# Create a case (receptionist intake)
curl -X POST http://localhost:8080/api/v1/agentic/cases \
  -H "Content-Type: application/json" \
  -d '{"raw_input": "Add contract testing to CI pipeline"}'

# Execute case (lawyer processes case)
curl -X POST http://localhost:8080/api/v1/agentic/cases/{case_id}/execute \
  -H "Content-Type: application/json" \
  -d '{"agent_role": "Executor", "task": "/execute"}'

# Get agent experience summary
curl http://localhost:8080/api/v1/agentic/experience
```

**Event Flow:**

1. **CaseCreated** → Receptionist receives and categorizes input
2. **CaseCategorized** → Case is filed with priority and metadata
3. **CaseReferenceGenerated** → Reference documents and workflow created
4. **CaseExecuted** → Agent processes the case with role-based execution
5. **CaseCompleted** → Case is completed with outcome and experience data

See [`docs/AGENTIC_SYSTEM_USAGE.md`](docs/AGENTIC_SYSTEM_USAGE.md) for complete usage instructions and [`docs/AGENTIC_SYSTEM.md`](docs/AGENTIC_SYSTEM.md) for system documentation.

### 🕸️ Unified Fabric & Watchmaker Mechanism (NEW)

The Unified Fabric provides a high-performance, asynchronous event bus and a distributed AI Safety bridge that connects GRID cognitive analysis with Coinbase financial execution.

**Key Features:**
- **AISafetyBridge**: Distributes safety validation from `wellness_studio` to all `E:/` projects.
- **Async Router Hooks**: De-blocks synchronous GRID routers with non-blocking safety checks.
- **Revenue Pipeline**: Automated flow from trading signals to portfolio execution with multi-system auditing.

**Run the Watchmaker Scenario:**
```powershell
# Demonstrates the full dynamic flow (Analysis -> Safety -> Trading -> Revenue)
python example_scenario.py
```

See `src/unified_fabric/` for implementation details.


### Health Check System


```bash
# Check all MCP server health
curl http://localhost:8080/health

# Individual server health
curl http://localhost:8081/health  # Database MCP
curl http://localhost:8082/health  # Filesystem MCP
curl http://localhost:8083/health  # Memory MCP
```


```bash
# Development stack

# Production stack with security

# Override configuration
```

## Development Workflow

### CI/CD & Monitoring

We use GitHub Actions for CI/CD with comprehensive validation:

```bash
# Watch the latest CI run
make watch-ci

```

Pipeline green checklist for release-bound changes:

1. Ensure `pyproject.toml` version matches the top entry in `CHANGELOG.md`
2. Run local gates: `ruff`, `pytest`, frontend lint/test/build, and package build
3. Keep generated artifacts out of git (for example `frontend/coverage/`, release scratch logs)
4. Require all workflow runs to pass on PR before merge
5. Re-check all workflow runs on `main` after merge

### Pre-Push Validation

Optimized pre-push hook ensures:

1. **Brain Integrity**: Validates `seed/topics_seed.json` structure
2. **Core Logic**: Runs fast unit tests (122+ passing)
3. **Hygiene**: Checks for large artifacts

### Tooling

- **Ruff**: Fast Python linter + formatter (`uv run ruff check .` / `uv run ruff format .`)
- **Mypy**: Type checker (`uv run mypy src/`)
- **Pytest**: Test runner (`uv run pytest tests/`)

**VS Code Tasks** (Ctrl+Shift+P → "Run Task"):

- `🧪 Tests · Run All` - Full test suite with coverage
- `✅ IDE · Validate Context` - Environment validation
- `🔍 RAG · Query` - Query knowledge base
- `📊 RAG · Index Docs` - Rebuild documentation index
- `🛰️ PULSAR · Dashboard` - System vitals dashboard

## Performance & Quality

### Test Coverage

- **168+ tests passing** across unit, integration, and agentic systems (31 new auth/billing tests)
- **100% pass rate** for new Unified Fabric core modules
- **Comprehensive coverage** for core intelligence, agentic system, and DDD patterns
- **CI/CD pipeline** with automated validation and deployment

### Performance Benchmarks

| Metric        | Before        | After         | Improvement |
| :------------ | :------------ | :------------ | :---------- |
| `cache_ops`   | 1,446 ops/sec | 7,281 ops/sec | **5x**      |
| `eviction`    | 36 ops/sec    | 6,336 ops/sec | **175x**    |
| `honor_decay` | 5,628 ops/sec | 3.1M ops/sec  | **550x**    |

## Documentation

### Core Documentation

- [`docs/WHAT_CAN_I_DO.md`](docs/WHAT_CAN_I_DO.md) - Complete capability overview
- [`docs/USER_ENGAGEMENT_GUIDE.md`](docs/USER_ENGAGEMENT_GUIDE.md) - User engagement & tailored experience
- [`docs/SKILLS_RAG_QUICKSTART.md`](docs/SKILLS_RAG_QUICKSTART.md) - Skills and RAG system guide
- [`docs/AGENTIC_SYSTEM.md`](docs/AGENTIC_SYSTEM.md) - Agentic system documentation
- [`docs/AGENTIC_SYSTEM_USAGE.md`](docs/AGENTIC_SYSTEM_USAGE.md) - Agentic system usage guide

### Architecture & Security

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) - **Complete architecture documentation with detailed Mermaid diagrams**
- [`docs/ARCHITECTURE_VISUAL_GUIDE.md`](docs/ARCHITECTURE_VISUAL_GUIDE.md) - **Visual quick reference guide for rapid understanding**
- [`docs/security/SECURITY_ARCHITECTURE.md`](docs/security/SECURITY_ARCHITECTURE.md) - Security architecture
- [`docs/EVENT_DRIVEN_ARCHITECTURE.md`](docs/EVENT_DRIVEN_ARCHITECTURE.md) - Event-driven design patterns
- [`docs/PERFORMANCE_OPTIMIZATION.md`](docs/PERFORMANCE_OPTIMIZATION.md) - Performance optimization guide

### Development Guides

- [`docs/structure/README.md`](docs/structure/README.md) - Repository structure guide
- [`docs/release/pipeline-runbook.md`](docs/release/pipeline-runbook.md) - Execution and post-execution pipeline green runbook
- [`BRANCH_ORGANIZATION.md`](BRANCH_ORGANIZATION.md) - Branch organization strategy and merge history
- [`docs/CLEANUP_SUMMARY.md`](docs/CLEANUP_SUMMARY.md) - Recent cleanup and reorganization
- [`SAFE_MERGES_COMPLETED.md`](SAFE_MERGES_COMPLETED.md) - Merge strategy and completion report

## Branch Organization

This repository follows a structured branching strategy for feature development and consolidation.

### Current Branch Structure

- **main** - Production-ready stable release
- **support branches / worktrees** - Short-lived investigation and implementation branches
  - Purpose: isolate experiments, safety reviews, and branch-level validation before promotion
  - Promotion policy: only audited, test-validated, safety-preserving changes are merged to `main`
  - Mitigation policy: regressions are blocked and documented in `docs/decisions/DECISIONS.md`

### Branch Naming Conventions

- `feature/` - New features and capabilities
- `fix/` - Bug fixes and patches
- `chore/` - Maintenance and housekeeping tasks
- `docs/` - Documentation updates
- `security/` - Security improvements and hardening
- `claude/` - Claude AI-generated branches (includes session ID suffix)

### Development Workflow

```bash
# Feature development
git checkout -b feature/your-feature-name

# Run tests before committing
uv run pytest tests/unit/ -v
uv run ruff check .

# Commit with conventional commits
git commit -m "feat(module): add new capability"

# Push to remote
git push -u origin feature/your-feature-name
```

### Quality Gates

Before merging to main:
- ✅ All tests passing (283+ tests)
- ✅ Code coverage ≥80%
- ✅ No linting errors (`ruff check`)
- ✅ No type errors (`mypy src/`)
- ✅ Security scan passing

See [`BRANCH_ORGANIZATION.md`](BRANCH_ORGANIZATION.md) for complete branch organization strategy and detailed merge history.

## License

MIT License - See [LICENSE](LICENSE) for details.

---

**GRID is now more organized, capable, and production-ready than ever! 🚀**
