Developer Overview

AEGIS (Agent Execution, Graph Intelligence & State) is a stateful runtime platform for enterprise AI agents. The current product target is oil and gas regulatory compliance in Texas, with an MVP shipping four AI agents for RRC (Railroad Commission of Texas) spacing, flaring, and compliance workflows.

What AEGIS Does

AEGIS automates the preparation and review of regulatory filings for Texas oil and gas operations. It provides:

AI agent execution with LangGraph-based stateful pipelines
Knowledge graph for oil and gas entity relationships (wells, leases, operators, permits)
Memory system with working memory, episodic recall, and deduplication
Human-in-the-loop (HITL) approval checkpoints for all regulatory filings
Compliance monitoring across spacing rules (Rule 37) and flaring rules (Rule 32)

Repository Layout

The project is a monorepo with 9 backend services, a Next.js frontend, and shared Python libraries:


aegis/
  agents/                 # 4 YAML agent configs (Rule 37, Rule 32, Compliance, Flaring)
  data/                   # RRC sample data
  docs/                   # Documentation and wiki
  frontend/               # Next.js 14 App Router (TypeScript, Tailwind, shadcn/ui)
  infrastructure/         # Docker configs, init SQL, startup/test scripts
  services/
    api-gateway/          # Go reverse proxy (port 8000)
    orchestration-engine/ # LangGraph agent runtime (port 8001)
    memory-service/       # Working + episodic memory (port 8002)
    knowledge-graph-service/ # Apache AGE graph (port 8003)
    approval-service/     # HITL approvals + audit trail (port 8004)
    ingestion-service/    # RRC scrapers + CSV import (port 8005)
    compliance-monitor/   # Deadline + rule tracking (port 8006)
    flaring-monitor/      # Flaring volumes + emissions (port 8007)
    auth-service/         # Email/password login + JWT auth (port 8009)
  shared/                 # Shared Python models and DB helpers
  specs/                  # Phase specifications (R1-R5)

Tech Stack

Layer	Technology	Notes
Languages	Python 3.12, Go 1.21+, TypeScript	Python for all AI services, Go for gateway
Agent Orchestration	LangGraph 0.1.x	StateGraph-based execution pipeline
LLM Routing	LiteLLM	gpt-4o primary, gpt-4o-mini fallback
Web Framework (Python)	FastAPI	Async/await, all Python services
Web Framework (Go)	net/http stdlib	Reverse proxy, middleware chain
Frontend	Next.js 14, Tailwind CSS, shadcn/ui	App Router, SSE streaming
Database	PostgreSQL 15 + pgvector + Apache AGE	Single DB instance with extensions
Cache / Memory	Redis 7	Working memory, injection ledger
Message Queue	Apache Kafka (Confluent 7.6.0)	Async event publishing
Dependency Management	Poetry (Python), Go modules	Per-service pyproject.toml
Data Modeling	Pydantic v2	Shared models in `aegis_shared`

Quick Links

Prerequisites — tools to install before you start
Local Setup — clone, configure, and run the platform
Environment Variables — every env var documented
First Run — seed data and verify the system works
Architecture Overview — high-level system diagram
LangGraph Pipeline — how agent execution works
Glossary — definitions for domain and technical terms