Lattice Lock Framework

A governance-first framework for AI-assisted software development with intelligent model orchestration.

Lattice Lock keeps humans and AI agents in perfect sync by enforcing code quality, architecture rules, and validation policies across your codebase. It bridges the gap between static analysis and runtime testing, ensuring your project adheres to its defined structure ("The Lattice").

Key Features

Feature	Description
Orchestrator	Intelligent multi-model routing across 8 AI providers (OpenAI, Anthropic, Google, xAI, Azure, Bedrock, Ollama, Grok) with automatic model selection
Sheriff	AST-based static analysis engine that catches architecture violations in milliseconds
Gauntlet	Runtime test generator that creates pytest suites from governance rules defined in `lattice.yaml`
Consensus	Multi-model voting engine for high-stakes decision making through model agreement
Admin API	FastAPI-based dashboard with JWT authentication and role-based access control
Agent System	90+ pre-defined AI agent specifications for specialized tasks
MCP Integration	Model Context Protocol support for extended AI capabilities

Quick Start

# Install the package
pip install lattice-lock

# Initialize a new project
lattice-lock init

# Create your governance rules in lattice.yaml
# (see Configuration section below)

# Run static analysis
lattice-lock validate

# Generate and run tests
lattice-lock test

# Query the AI orchestrator
lattice-lock ask "Explain the architecture of this project"

Minimal Example

Create a lattice.yaml in your project root:

version: "2.1"
rules:
  - id: "no-print"
    description: "Use logger instead of print statements in production code."
    severity: "error"
    scope: "src/**/*.py"
    excludes: ["scripts/*", "tests/*"]
    forbids: "node.is_call_to('print')"

Then validate:

lattice-lock validate
# Output: [ERROR] no-print: Use logger instead of print... (src/bad_code.py:2)

Installation

From PyPI

pip install lattice-lock

From Source

git clone https://github.com/klappe-pm/lattice-lock-framework.git
cd lattice-lock-framework
pip install -e ".[dev]"

Requirements

Python: 3.10, 3.11, or 3.12
At least one AI provider API key (for orchestration features)

Core Components

Orchestrator

The Orchestrator provides intelligent model routing and selection across multiple AI providers. It analyzes tasks and routes them to the most appropriate model based on capability scoring.

Supported Providers:

Provider	Models	Context
OpenAI	GPT-4, GPT-4 Turbo, GPT-3.5, O1	Up to 128K
Anthropic	Claude 3.x, Claude 4.x	Up to 200K
Google	Gemini 2.x, Gemini 1.5	Up to 2M
xAI	Grok models	Up to 2M
Azure OpenAI	Azure-hosted OpenAI models	Varies
AWS Bedrock	Multiple providers via AWS	Varies
Ollama	Local open-source models	Varies
Grok	Custom implementation	Up to 2M

Usage:

from lattice_lock.orchestrator import ModelOrchestrator

orchestrator = ModelOrchestrator()

# Auto-route to best model
response = await orchestrator.route("Analyze this code for security issues", context)

# List available models
models = orchestrator.list_models()

# Get routing recommendation
recommendation = orchestrator.analyze_task("Design a microservices architecture")

CLI:

# List all available models
lattice-lock orchestrator list

# Route a task to the best model
lattice-lock orchestrator route "Design a REST API"

# Analyze task for model recommendations
lattice-lock orchestrator analyze "Implement authentication system"

Sheriff

Sheriff is the static analysis engine that uses AST (Abstract Syntax Tree) traversal to catch architecture violations in milliseconds without running your code.

Key Features:

AST-based Python analysis
Rule-based violation detection
Caching for performance
Multiple output formats

Usage:

from lattice_lock.sheriff import run_sheriff

# Run analysis on current project
violations = run_sheriff()

for violation in violations:
    print(f"[{violation.severity}] {violation.rule_id}: {violation.message}")
    print(f"  Location: {violation.file}:{violation.line}")

CLI:

# Run static analysis
lattice-lock validate

# With specific scope
lattice-lock validate --scope src/

Gauntlet

Gauntlet generates pytest test suites from your governance rules defined in lattice.yaml. It creates runtime tests for semantic properties that cannot be checked statically.

Usage:

from lattice_lock.gauntlet import GauntletGenerator

generator = GauntletGenerator()

# Generate tests from lattice.yaml
tests = generator.generate()

# Run generated tests
results = generator.run()

CLI:

# Generate and run governance tests
lattice-lock test

# Alias
lattice-lock gauntlet

Consensus Engine

The Consensus Engine enables high-stakes decision making by querying multiple AI models and aggregating their responses through voting.

Usage:

from lattice_lock.consensus import ConsensusEngine

consensus = ConsensusEngine()

# Get multi-model consensus on a decision
result = await consensus.vote(
    prompt="Should we use microservices or monolithic architecture?",
    models=["gpt-4", "claude-3-opus", "gemini-2.0-pro"],
    threshold=0.7  # 70% agreement required
)

print(f"Decision: {result.decision}")
print(f"Confidence: {result.confidence}")
print(f"Model votes: {result.votes}")

Configuration

Environment Variables

Copy .env.example to .env and configure your settings:

cp .env.example .env

Required (at least one provider):

# AI Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
XAI_API_KEY=...

Optional:

# AWS Bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# Local Models
OLLAMA_HOST=http://localhost:11434

# Feature Control
LATTICE_FEATURE_PRESET=full          # minimal, standard, full
LATTICE_DISABLED_FEATURES=           # Comma-separated: sheriff,gauntlet,feedback,rollback,consensus,mcp
LATTICE_DEFAULT_MODEL=auto           # auto, manual, or specific model ID
LATTICE_LOG_LEVEL=INFO               # DEBUG, INFO, WARNING, ERROR, CRITICAL

# Database
DATABASE_URL=sqlite:///lattice.db

# Admin API (for dashboard)
ADMIN_SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret

Lattice Policy File

The lattice.yaml file is the constitution of your project. It defines all governance rules.

version: "2.1"

# Global settings
settings:
  severity_threshold: warning
  fail_fast: false

# Rule definitions
rules:
  - id: "no-print"
    description: "Use logger instead of print statements"
    severity: error
    scope: "src/**/*.py"
    excludes: ["scripts/*", "tests/*"]
    forbids: "node.is_call_to('print')"

  - id: "max-function-length"
    description: "Functions should not exceed 50 lines"
    severity: warning
    scope: "src/**/*.py"
    check: "node.line_count <= 50"

  - id: "require-docstrings"
    description: "Public functions must have docstrings"
    severity: error
    scope: "src/**/*.py"
    requires: "node.has_docstring()"
    filter: "node.is_public_function()"

CLI Reference

Core Commands

Command	Description
`lattice-lock init`	Initialize a new project with lattice.yaml
`lattice-lock validate`	Run static analysis (Sheriff)
`lattice-lock test`	Generate and run governance tests (Gauntlet)
`lattice-lock compile`	Compile lattice.yaml into validation artifacts
`lattice-lock ask "<prompt>"`	Query the AI orchestrator
`lattice-lock doctor`	Diagnose project configuration issues
`lattice-lock feedback`	Submit feedback about the framework

Orchestrator Commands

lattice-lock orchestrator list              # List available models
lattice-lock orchestrator route "<task>"    # Route task to best model
lattice-lock orchestrator analyze "<task>"  # Get model recommendations

Admin Commands

lattice-lock admin start      # Start admin dashboard server
lattice-lock admin users      # Manage users
lattice-lock admin keys       # Manage API keys

Context Handoff

lattice-lock handoff export   # Export current context
lattice-lock handoff import   # Import context from another session

MCP Server

lattice-lock mcp              # Start MCP server
lattice-lock mcp --stdio      # Start in stdio mode

Admin Dashboard

Lattice Lock includes a FastAPI-based admin dashboard for managing users, monitoring usage, and configuring the system.

Starting the Dashboard

# Using CLI
lattice-lock admin start

# Using uvicorn directly
uvicorn lattice_lock.admin:admin_app --port 8080

Features

JWT Authentication: Secure token-based auth with bcrypt password hashing
Role-Based Access Control: Admin, user, and read-only roles
User Management: Create, update, delete users
API Key Management: Generate and revoke API keys
Health Monitoring: /api/v1/health endpoint

API Endpoints

The admin API provides 29 REST endpoints:

GET    /api/v1/health          # Health check
POST   /api/v1/auth/login      # User login
POST   /api/v1/auth/logout     # User logout
GET    /api/v1/users           # List users
POST   /api/v1/users           # Create user
GET    /api/v1/users/{id}      # Get user
PUT    /api/v1/users/{id}      # Update user
DELETE /api/v1/users/{id}      # Delete user
# ... and more

Frontend Dashboard

A React-based frontend is included in frontend/:

cd frontend
npm install
npm run dev      # Development server on port 5173
npm run build    # Production build

Feature Flags

Control which features are enabled using environment variables.

Presets

Preset	Features
`full` (default)	All features enabled
`standard`	Orchestrator, Sheriff, Gauntlet
`minimal`	Core Orchestrator only

LATTICE_FEATURE_PRESET=standard

Granular Control

Disable specific features:

LATTICE_DISABLED_FEATURES=sheriff,consensus,mcp

Available feature flags:

sheriff - Static analysis
gauntlet - Test generation
feedback - User feedback collection
rollback - Transaction rollback system
consensus - Multi-model voting
mcp - Model Context Protocol

Project Structure

lattice-lock-framework/
├── src/lattice_lock/           # Core Python package
│   ├── orchestrator/           # Model routing & selection (8 providers)
│   ├── sheriff/                # Static analysis engine (AST-based)
│   ├── gauntlet/               # Runtime test generation
│   ├── consensus/              # Multi-model voting engine
│   ├── cli/                    # Click-based CLI
│   ├── admin/                  # FastAPI admin dashboard
│   ├── dashboard/              # WebSocket monitoring
│   ├── database/               # SQLAlchemy repository pattern
│   ├── agents/                 # Agent definitions & templates
│   ├── config/                 # Feature flags & app config
│   ├── mcp/                    # Model Context Protocol
│   └── utils/                  # Utility functions
│
├── frontend/                   # React + Vite dashboard
├── tests/                      # Test suite (87 files)
├── docs/                       # Documentation (30+ guides)
├── agents/                     # AI agent definitions (90+)
├── scripts/                    # Automation scripts
└── infrastructure/             # Deployment configs

Development

Setup

# Clone and install with dev dependencies
git clone https://github.com/klappe-pm/lattice-lock-framework.git
cd lattice-lock-framework
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# All tests
make test

# Quick tests only
make test-quick

# With coverage
pytest tests/ --cov=src/lattice_lock --cov-report=html

# Specific test file
pytest tests/core/test_feedback.py

Code Quality

# Run all linters
make lint

# Auto-format code
make format

# Type checking
make type-check

# Full CI check
make ci

Make Targets

Target	Description
`make lint`	Run Ruff, Black, MyPy, Lattice Validate
`make format`	Auto-format with Black and Ruff
`make test`	Run unit tests
`make test-quick`	Run critical tests only
`make type-check`	Static type checking
`make ci`	Full CI (lint, type-check, test)
`make deps`	Update dependencies
`make clean`	Remove build artifacts
`make pre-commit`	Run all pre-commit checks

Code Standards

File Naming: lowercase_with_underscores.py
Class Names: PascalCase
Formatting: Black (100 char line length)
Linting: Ruff + Pylint
Type Hints: Required for all public APIs
Docstrings: Google-style

See docs/CONTRIBUTING.md for the complete coding standards (single source of truth).

Documentation

Documentation is organized in the docs/ directory:

Directory	Content
docs/guides/	29 tutorial guides covering all features
docs/architecture/	System design and architecture docs
docs/reference/	API reference documentation
docs/examples/	Example projects and code samples
docs/testing/	Testing guides and strategies

Key Guides

Installation Guide - Getting started
Governance Guide - End-to-end workflow
Model Orchestration - Using the orchestrator
Local Models Setup - Ollama configuration
Troubleshooting - Common issues

Contributing

We welcome contributions! Please read docs/CONTRIBUTING.md first - it is the single source of truth for all coding standards, naming conventions, and workflow requirements.

Quick Contribution Checklist

Fork the repository
Create a branch: your-name/feature-description
Follow naming conventions (lowercase with underscores)
Add tests for new features
Run make ci to verify all checks pass
Open a PR targeting main
Add required labels: type (feat, fix, etc.) + source (human, llm, devin)

Git Workflow

Single permanent branch: main
Merge strategy: Squash-and-merge only
CI Requirements: Tests, lint, and typecheck must pass
Review: @greptileai is auto-assigned

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

License

This project is licensed under the MIT License. See LICENSE.md for details.

Acknowledgments

Lattice Lock Framework is built with:

FastAPI - Admin API
Click - CLI framework
Pydantic - Data validation
SQLAlchemy - Database ORM
Rich - Terminal formatting
httpx - Async HTTP client

Built for humans and AI agents working in perfect sync.

Name		Name	Last commit message	Last commit date
Latest commit History 564 Commits
.githooks		.githooks
.github		.github
.mcp		.mcp
_gitignore_folders/_design/_design_style_guides		_gitignore_folders/_design/_design_style_guides
agents		agents
docs		docs
frontend		frontend
infrastructure/terraform		infrastructure/terraform
project_management		project_management
scripts		scripts
shared		shared
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LATTICE_YAML_README.md		LATTICE_YAML_README.md
LICENSE.md		LICENSE.md
MODELS.md		MODELS.md
Makefile		Makefile
PROJECT_INDEX.md		PROJECT_INDEX.md
README.md		README.md
SECURITY.md		SECURITY.md
lattice_lock_agent_index.md		lattice_lock_agent_index.md
pyproject.toml		pyproject.toml
requirements-dev.lock		requirements-dev.lock
requirements.lock		requirements.lock
version.txt		version.txt

License

klappe-pm/_lattice_lock_framework

Folders and files

Latest commit

History

Repository files navigation

Lattice Lock Framework

Table of Contents

Key Features

Quick Start

Minimal Example

Installation

From PyPI

From Source

Requirements

Core Components

Orchestrator

Sheriff

Gauntlet

Consensus Engine

Configuration

Environment Variables

Lattice Policy File

CLI Reference

Core Commands

Orchestrator Commands

Admin Commands

Context Handoff

MCP Server

Admin Dashboard

Starting the Dashboard

Features

API Endpoints

Frontend Dashboard

Feature Flags

Presets

Granular Control

Project Structure

Development

Setup

Running Tests

Code Quality

Make Targets

Code Standards

Documentation

Key Guides

Contributing

Quick Contribution Checklist

Git Workflow

Support

License

Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages