AegisMind 🛡️

AegisMind is an enterprise-grade, distributed AI research platform engineered around a polyglot microservice architecture (Go + Python). It combines a high-throughput Go Gateway for request handling, session management, and SSE streaming with a robust Python AI Service for machine learning pipelines, dense vector indexing, LangGraph RAG orchestration, and multi-agent CrewAI execution.

---

🏛️ System Architecture

graph TD
    Client[Web client / User] -->|HTTP / SSE GET| GoGateway[Go Gateway: Port 8080]
    subgraph Go Gateway layer
        GoGateway -->|Checks L1| L1Cache["InMemoryVectorCache (Mock FAISS)"]
        GoGateway -->|SSE Flusher| SSEProxy[SSE Stream Proxy]
    end
    GoGateway -->|gRPC Client Pool| PyService[Python AI Service: Port 50051]
    subgraph Python AI Service layer
        PyService -->|Unary Classify| Safety[CPU Safety Classifier: TensorFlow]
        PyService -->|Server Stream Report| LangGraph[LangGraph RAG Workflow]
        LangGraph -->|Node 5| CrewAI[CrewAI Multi-Agent Team]
        CrewAI -->|Researcher| Ollama[Ollama Llama3 / HF fallback]
        CrewAI -->|Critic| Claude[Anthropic Claude 3.5 Sonnet]
        CrewAI -->|Writer| GPT4o[OpenAI GPT-4o]
        LangGraph -->|Generate Embeddings| Embedding[BGE-large + Re-ranker]
        LangGraph -->|Hybrid Search| Qdrant[(Qdrant Vector DB)]
        LangGraph -->|Fallback| Chroma[(ChromaDB In-Memory)]
    end

Loading

---

🛠️ Key Architectural Implementations

Phase 2 — RAG Pipeline (LangGraph)

Node	Component	Description
1	TensorFlowGuard	Regex + Keras classifier blocks prompt injections, jailbreaks, malware keywords
2	Query Expansion	Generates targeted search variants (cycles broaden on retry)
3	Hybrid Retrieval	Qdrant dense search → BGE cross-encoder re-ranking (Chroma fallback)
4	Groundedness Grader	Scores relevance; loops back up to 3× if score < 0.7
5	CrewAI Synthesis	Triggers the multi-agent research team (Phase 3)

Phase 3 — Multi-Agent CrewAI Team

Three specialised agents execute sequentially inside LangGraph Node 5:

Agent	Role	Primary LLM	Fallback
Researcher	Extract facts from vector index	Ollama Llama3 (local)	HuggingFace / mock
Critic	Flag hallucinations vs. source context	Anthropic Claude 3.5 Sonnet	Mock critic
Writer	Produce Markdown report with citations	OpenAI GPT-4o	Mock writer

Streaming bridge: CrewAI step callbacks emit CHUNK_TYPE_AGENT_STATE, CHUNK_TYPE_CITATION, and CHUNK_TYPE_TOKEN chunks through the gRPC adapter to the Go SSE gateway.

Resilient gRPC Client Connection Pooling

The Go Gateway implements a thread-safe connection manager (grpcclient.ClientPool) that multiplexes request payloads over a configurable pool of physical TCP channels. It performs automated health checking and triggers reconnects if channels experience transient network errors.

Hard Context Propagation (Cancellation Guard)

To optimize cloud execution costs and GPU utilization:

• The HTTP SSE request context (r.Context()) is propagated directly to the gRPC client's stream request.
• If a client disconnects, Go immediately cancels the gRPC context.
• The Python gRPC handler evaluates context.is_active() at every LangGraph node boundary and CrewAI agent step, raising asyncio.CancelledError to instantly kill multi-agent execution.

Direct SSE Stream Proxying

Leverages Go's http.Flusher to capture and flush downstream tokens dynamically. Includes explicit headers:

• X-Accel-Buffering: no — Prevents Nginx/reverse proxy buffering
• Access-Control-Allow-Origin: * — CORS for browser clients
• Cache-Control: no-cache / Connection: keep-alive — Real-time delivery

SSE event routing:

gRPC Chunk Type	SSE Event
CHUNK_TYPE_AGENT_STATE	event: message
CHUNK_TYPE_TOKEN	event: message
CHUNK_TYPE_CITATION	event: message
CHUNK_TYPE_COMPLETE	event: complete
Errors	event: error

---

📁 Project Structure

aegis-mind/
├── .gitignore
├── Makefile
├── docker-compose.yml          # Qdrant + Redis
├── proto/aegismind/v1/         # Shared gRPC contract
├── go-gateway/
│   ├── cmd/gateway/main.go
│   └── internal/
│       ├── api/sse_handler.go  # HTTP SSE stream proxy
│       └── grpcclient/client.go
└── python-ai-service/
    └── app/
        ├── main.py             # gRPC server entry point
        ├── ml/
        │   ├── safety_guard.py # TensorFlow safety classifier
        │   └── embeddings.py   # BGE embeddings + Qdrant/Chroma
        ├── rag/
        │   └── rag_workflow.py # LangGraph 5-node state machine
        ├── agents/
        │   └── crew_engine.py  # CrewAI multi-agent team
        └── grpc_server/
            └── adapter.py      # Stream adapter + cancellation guard

---

🚀 Setup & Execution

📋 Prerequisites

• Go (v1.21+)
• Python (v3.9+)
• Protobuf Compiler (protoc)
• Docker & Docker Compose
• (Optional) Ollama with llama3 for local Researcher LLM
• (Optional) ANTHROPIC_API_KEY and OPENAI_API_KEY for Critic/Writer agents

📦 Python Dependencies

cd python-ai-service
pip install -r requirements.txt
cd ..

🔑 Environment Variables (Optional)

Variable	Default	Purpose
OLLAMA_BASE_URL	http://localhost:11434	Ollama endpoint for Researcher
OLLAMA_MODEL	llama3	Ollama model name
ANTHROPIC_API_KEY	—	Claude 3.5 Sonnet for Critic
OPENAI_API_KEY	—	GPT-4o for Writer
QDRANT_HOST	localhost	Qdrant vector DB host
QDRANT_PORT	6333	Qdrant port
GRPC_PORT	50051	Python gRPC listen port
PORT	8080	Go Gateway HTTP port

---

🕹️ Developer Workflows

The platform leverages root Makefile targets:

1. Compile Protobufs

make proto

2. Spin Up External Databases

make docker-up

3. Run Microservices Concurrently

make dev

---

🧪 Verification & Testing

🟢 Health Check

curl http://localhost:8080/health

Response:

{"status":"healthy","service":"go-gateway"}

🌊 Stream a Research Query

curl -N "http://localhost:8080/stream?prompt=Explain+hybrid+RAG+retrieval+in+AegisMind"

Expected SSE events:

event: message
data: {"type":1,"content":"[Safety Classifier] Query verified (score=0.900). Proceeding.","agent_name":"Safety Classifier",...}

event: message
data: {"type":1,"content":"[Query Expansion] Generated 4 targeted search variants.",...}

event: message
data: {"type":1,"content":"[Hybrid Search & Re-rank] Retrieved and re-ranked 3 documents.",...}

event: message
data: {"type":3,"content":"[Mock Document 0] AegisMind is an enterprise-grade...",...}

event: message
data: {"type":1,"content":"[Researcher Agent] Querying vector index and extracting facts…",...}

event: message
data: {"type":1,"content":"[Critic Agent] Cross-examining findings against source context…",...}

event: message
data: {"type":2,"content":"# Research Report ",...}

event: complete
data: {"status":"finished","content":"AegisMind research pipeline completed successfully.",...}

🔴 Unsafe Query (Safety Guard)

curl -N "http://localhost:8080/stream?prompt=attempt+malware+exploit+on+server"

Expected:

event: error
data: {"label":"MALWARE_KEYWORD","message":"unsafe query detected",...}