GRID — Geometric Resonance Intelligence Driver

Engineering at a Glance

Built primarily by a solo engineer over 6 months — from blank templates to a production-hardened framework with CI, security layers, and full test infrastructure.

The architecture is domain-driven with event-driven agentic workflows — not a monolith, not a microservice explosion. Each package has clear boundaries, its own tests, and ships as an independent wheel.

For clients: If you're evaluating this repo as part of a proposal, the CI pipeline, CHANGELOG, and test structure tell the story better than any portfolio page. The code is the portfolio.

GRID is a privacy-first code intelligence framework that helps you understand complex codebases using local AI models. Your code never leaves your machine.

pip install grid-intelligence
grid --help

Or install from source for development:

git clone https://github.com/GRID-INTELLIGENCE/GRID.git
cd GRID
uv sync --group dev --group test
uv run grid --help

For contributor setup see docs/INSTALLATION.md. Environment template: config/environment/.env.example.

Why GRID?

At a Glance

Core Capabilities

• 9 Cognition Patterns — Flow · Spatial · Rhythm · Color · Repetition · Deviation · Cause · Time · Combination
• Local-First RAG — ChromaDB + Ollama. Optional cloud hybrid (OpenAI / Anthropic / Gemini) via RAG_LLM_MODE=external
• Cognitive Decision Support — Light of the Seven architecture for bounded rationality
• Agentic System — Event-driven case management (receptionist → lawyer → executor)
• Transition Gate — Sealed-envelope HMAC-SHA256 handshake for cross-partition artifact transfers
• Search with Guardrails — Auth, rate limiting, input sanitization, admin-gated schema routes
• Unified Fabric — Async event bus and distributed AI Safety bridge
• Authentication & Billing — JWT + bcrypt, token revocation, tier-based usage tracking

Quick Start (Contributors)

uv sync --group dev --group test   # Creates .venv, installs everything
uv run pytest                      # Run tests
uv run ruff check .                # Lint
uv run python -m grid --help       # CLI

[!IMPORTANT] Use uv add to manage packages — not pip install. See pyproject.toml and uv.lock.

uv add <package>                   # Runtime dependency
uv add --group dev <package>       # Dev-only
uv lock                            # Regenerate lockfile
uv sync                            # Sync .venv to lockfile

Project Structure

GRID/
├── src/                       # Source code (9 wheel packages)
│   ├── grid/                  #   Core intelligence engine
│   ├── application/           #   FastAPI (Mothership API)
│   ├── cognitive/             #   Cognitive architecture
│   ├── tools/                 #   RAG, utilities
│   ├── search/                #   Search service + guardrails
│   ├── mycelium/              #   Comprehension frontend
│   ├── infrastructure/        #   Infra adapters
│   ├── unified_fabric/        #   Async event bus + safety bridge
│   └── vection/               #   Motion & perception
├── tests/                     # Test suite (4490+ test functions)
├── safety/                    # GUARDIAN rule engine, PII privacy
├── security/                  # Network interceptor, forensics
├── boundaries/                # Boundary engine, transition gate
├── config/                    # All configuration & structured data
│   ├── deploy/                #   Railway, Render deployment configs
│   ├── contracts/             #   OpenAPI specs
│   └── prompts/               #   Prompt templates
├── schemas/                   # JSON schemas (OpenAPI, telemetry, …)
├── scripts/                   # Build, CI, and demo scripts
├── docs/                      # Documentation (architecture, guides, ADRs)
│   ├── reports/               #   Audit & analysis reports
│   └── checkpoints/           #   Session checkpoints
├── landing/                   # Marketing site (Netlify)
├── frontend/                  # Web client
└── pyproject.toml             # Project config (uv)

What's New

v2.8.0 — Admission Gate & Entity Persistence (March 2026)

• Admission Gate — Top-of-stack ethical participation enforcement with 6 sequential gates, 3-tier penalty escalation, and entity attribution
• Entity Persistence — SQLite-backed entity state with async CRUD and startup hydration
• Frontend Dashboard — Admission page with live stats, policy billboard, bannered entities table
• REST API — 7 endpoints under /admission/* with admin-protected penalty management

Development Workflow

CI Pipeline (GitHub Actions)

Quality Gates

Before merging to main:

1. uv run ruff check . — zero errors
2. uv run pytest tests/ -q --tb=short — all passing
3. pyproject.toml version matches top CHANGELOG.md entry
4. No DEBUG=true or ENABLE_DEV_TOKEN in production paths
5. No untracked files in src/ or tests/

Tooling

Privacy & External LLM

GRID is local-first by default. No data leaves your machine unless you explicitly opt in.

When using external providers, prompts and responses are sent to the chosen provider.

The Story

GRID began in November 2025 as blank templates and empty journals. By December it became a system — domain-driven architecture, security foundations, and a core principle:

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

There's a state in the pattern engine called MIST — "high confidence that we don't know." That epistemic humility, inspired by Carl Jung, shapes everything we build.

Nov 2025 → First commit. Blank templates.
Dec 2025 → Architecture cleanup. Security foundation. DDD.
Jan 2026 → Cognitive layer. RAG optimization. Production hardening.
Feb 2026 → 540+ files. Environmental Intelligence. Mycelium. v2.6+.
Mar 2026 → 1270+ files. Admission gate. Entity persistence. v2.8.0.
Apr 2026 → 1490+ files. 4490+ tests. TS 6.0, strict asyncio, CI green.

GRID is built by someone who cares about doing things right — principled, not perfect.

Documentation

License

MIT — see LICENSE.