Skip to content

QUICK_START.md

Latest commit

 

History

History
192 lines (145 loc) · 4.17 KB

QUICK_START.md

File metadata and controls

192 lines (145 loc) · 4.17 KB

Lexecon Quick Start Guide

Current Status ✓

Server: Running on http://localhost:8000 with 4 workers Performance: Optimized for concurrent load Databases: SQLite with WAL mode enabled Test Suite: 1,087 tests (currently running)

Start Server

# Quick start
./start_server.sh

# Or manually with multiple workers
export PYTHONPATH=/Users/air/Lexecon/src:$PYTHONPATH
python3 -m uvicorn lexecon.api.server:app --host 0.0.0.0 --port 8000 --workers 4

Test Endpoints

# Health check
curl http://localhost:8000/health

# System status
curl http://localhost:8000/status

# API documentation
open http://localhost:8000/docs

Make a Decision

curl -X POST http://localhost:8000/decide \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "user:alice",
    "proposed_action": "access_customer_data",
    "tool": "database_query",
    "user_intent": "customer support",
    "data_classes": ["customer_data"],
    "risk_level": 2,
    "context": {
      "purpose": "support_ticket",
      "ticket_id": "T12345"
    }
  }'

Performance Benchmarks

After Optimization (SQLite WAL + 4 Workers):

Test P95 Latency Throughput Success Rate
Sequential 32ms ~50 req/sec 100%
Concurrent (10) 156ms ~30 req/sec 100%
Concurrent (50) 549ms ~30 req/sec 100%

Improvements from single-worker:

  • Sequential: 4x faster (134ms → 32ms)
  • Concurrent 10: 4.6x faster (713ms → 156ms)
  • Concurrent 50: 3.5x faster (1900ms → 549ms)
  • Success rate: 1% → 100%

Optimizations Applied

  1. SQLite WAL Mode - Better concurrent write handling
  2. Multi-worker Uvicorn - 4 workers for parallel request processing
  3. Cache Settings - 40MB cache per database
  4. Fixed Module Imports - cache_api_response, cache_compliance_mapping, cache_decision

Configuration

Environment variables in .env:

# Database (optimized for concurrency)
LEXECON_DATABASE_URL=sqlite:///./lexecon_ledger.db
SQLITE_JOURNAL_MODE=WAL
SQLITE_SYNCHRONOUS=NORMAL
SQLITE_CACHE_SIZE=10000

# API
PORT=8000
LEXECON_BASE_URL=http://localhost:8000

# Rate Limiting
LEXECON_RATE_LIMIT_ENABLED=true
LEXECON_RATE_LIMIT_GLOBAL_PER_IP=1000/60

Run Tests

# Full suite (excluding 2 outdated test files)
pytest tests/ \
  --ignore=tests/test_rate_limiter.py \
  --ignore=tests/test_security_headers.py \
  -v

# Quick validation
pytest tests/test_api.py -v

# With coverage
pytest --cov=lexecon --cov-report=term-missing

Database Files

All SQLite databases use WAL mode:

  • lexecon_ledger.db - Main audit trail (2,595+ entries)
  • lexecon_auth.db - User authentication
  • lexecon_responsibility.db - Accountability records
  • lexecon_interventions.db - Escalations/overrides
  • lexecon_export_audit.db - Export history

Next Steps

For Production (when ready):

  1. Add PostgreSQL - Better concurrent performance

    # Using docker-compose.dev.yml
docker-compose -f docker-compose.dev.yml up postgres redis

  2. Add Redis - API response caching

    # Update .env
REDIS_URL=redis://localhost:6379/0

  3. Scale workers - Based on load

    --workers $(nproc)  # One per CPU core

For Development:

  1. Frontend Integration - Connect React dashboard to API
  2. Load Testing - k6 scripts in tests/k6/
  3. Fix Test Suite - Update RateLimitConfig tests

Troubleshooting

Port already in use:

lsof -ti:8000 | xargs kill -9

Reset databases:

rm -f lexecon*.db*
# Server will recreate on startup

Module import errors:

export PYTHONPATH=/Users/air/Lexecon/src:$PYTHONPATH

API Examples

See /docs endpoint when server is running for:

  • Complete API reference
  • Interactive testing
  • Request/response schemas
  • Authentication flows

Performance Testing

# Run performance test
python3 /tmp/lexecon_perf_test.py

# Expected results:
# - 100% success rate
# - P95 < 50ms sequential
# - P95 < 200ms concurrent (10)
# - P95 < 600ms concurrent (50)

Version: 0.1.0 Last Updated: 2026-01-23 Status: Production-ready with SQLite, scales to PostgreSQL