Rapid Agentic Capability Engine & Runtime
A self-contained, portable agentic AI demonstration framework for enterprise and government environments. RACER spins up intelligent AI agents against your own approved LLM endpoint — a self-hosted vLLM server, OpenAI, Azure OpenAI, Google Gemini, or AWS Bedrock — with zero proprietary infrastructure dependencies.
git clone → cp .env.example .env → docker compose up → working demo in under 30 minutes
| Component | Port | Purpose |
|---|---|---|
racer-api |
8000 | FastAPI agent runtime: task routing, archetype-driven agents, LLM provider shim |
n8n |
5678 | Workflow orchestrator with a pre-built demo workflow |
redis |
internal | Task result state (1 hr TTL) |
Agents are defined as archetypes — plain markdown files with YAML frontmatter
(archetypes/*.md). v0.1 ships three: researcher (structured reports),
analyst (courses of action and tradeoffs), and planner (sequenced execution
orders). Incoming tasks are routed automatically by botRouter-lite (keyword
classification with LLM zero-shot fallback), or you can pin an archetype per request.
Prerequisites: Docker with Compose v2, and network reach to an LLM endpoint.
git clone https://github.com/Dilbertian/racer.git
cd racer
cp .env.example .env # point at your LLM endpoint (see below)
docker compose up -d --build
curl http://localhost:8000/healthOr in one command (also runs the full demo):
./scripts/run_demo.shVerify an install with health checks plus smoke tests:
./scripts/validate.shEverything is driven by .env — no code changes to swap providers. The default
configuration targets any OpenAI-compatible endpoint (vLLM, Ollama, LiteLLM):
LLM_PROVIDER=openai
OPENAI_API_KEY=fake-key # placeholder ok for unauthenticated endpoints
OPENAI_BASE_URL=http://192.168.8.30:8000/v1 # your endpoint
OPENAI_MODEL=qwen3-32b-awq.env.example documents the alternatives: OpenAI proper, Azure OpenAI, Google
Gemini (pip install google-genai), and AWS Bedrock (pip install boto3).
UNCLASSIFIED // FICTIONAL — all scenario data is invented for demonstration.
A fictional forward air base has taken ballistic missile strikes: runway cratered, medical overwhelmed, fuel destroyed, SATCOM down. A pre-positioned network of 12 autonomous resupply drones must be tasked: triage needs, match payloads, route around denied airspace, and sequence sorties into waves — as a commander-ready execution order.
curl -X POST http://localhost:8000/scenarios/wraith/runRACER loads the synthetic scenario files (scenarios/wraith/), routes to the
planner archetype, and returns a structured execution order in roughly 90 seconds
(model-dependent). See scenarios/wraith/README.md
for the scenario details and grading criteria.
Scope note for demo audiences: v0.1 agents reason entirely over the packaged scenario files — there is no live data search or tool execution in this release. Archetype
capabilitiesare declarative. Live data integration (tool use) is the v0.2 headline feature; the archetype/runner architecture is built for it.
Interactive docs at http://localhost:8000/docs once running.
| Endpoint | Description |
|---|---|
GET /health |
Health + active provider |
GET /archetypes |
List available archetypes |
POST /task |
Run a task: {"query": "...", "archetype?": "...", "scenario?": "...", "context?": "..."} |
POST /task/stream |
Same, streamed as Server-Sent Events |
GET /task/{task_id} |
Retrieve a completed result (1 hr retention) |
GET /scenarios |
List demo scenarios |
POST /scenarios/{name}/run |
Run a scenario end to end |
Task responses include the markdown result plus sources, confidence,
elapsed_ms, archetype_used, and model_used.
Import n8n/workflows/wraith-reconstitution.json into n8n (http://localhost:5678
→ Workflows → Import from File), activate it, and POST to its webhook to trigger
the WRAITH demo through the orchestrator. The workflow only passes the scenario
name to the API — all scenario data loading happens inside the RACER runtime.
Licensing note: n8n is fair-code licensed under the Sustainable Use License. Self-hosted internal use is permitted; offering n8n to third parties as part of a managed service may not be. If your delivery model wraps RACER in a service contract, review the license first. The orchestration layer is deliberately thin — the workflow is a single HTTP call — so substituting Apache Airflow, Temporal, or a plain scheduler is straightforward if licensing rules n8n out.
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r api/requirements.txt
cp .env.example .env
uvicorn api.main:app --port 8000Redis is optional off-Docker; without it, task results are kept in process memory.
pytest tests/unit tests/integration -v # no network or services needed (mocked LLM)
pytest tests/live -v # real LLM calls; auto-skips if endpoint unreachable
docker compose up -d && pytest tests/smoke -v # full stack; auto-skips if API downapi/ FastAPI app, router, runner, archetype/scenario loaders, LLM shim
archetypes/ Agent definitions (markdown + YAML frontmatter)
scenarios/ Demo scenario data (synthetic, clearly marked FICTIONAL)
n8n/workflows/ Importable orchestration workflows
tests/ unit / integration / live / smoke tiers
scripts/ run_demo.sh, validate.sh
Authored and tested against a live vLLM endpoint (unit, integration, and live
tiers all passing). The Docker/n8n layer is authored but not yet executed on a
Docker host — run ./scripts/validate.sh after your first docker compose up
and pin the n8n image version once validated.
- Docker + Docker Compose
- An OpenAI-compatible API key (Gemini, OpenAI, etc.)
git clone https://github.com/Dilbertian/racer.git
cd racer
cp .env.example .envEdit .env — recommended for most dev environments (Gemini):
LLM_PROVIDER=openai
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
OPENAI_API_KEY=your_gemini_api_key_here
OPENAI_MODEL=gemini-2.5-flashThen:
docker compose up -d
curl http://localhost:8000/healthExpected: {"status":"ok","version":"0.1.0","provider":"openai",...}
Import the three archetype workflows from n8n/workflows/ into your n8n instance:
| File | Archetype | Purpose |
|---|---|---|
racer-researcher.json |
Researcher | Intelligence gathering & synthesis |
racer-analyst.json |
Analyst | COA development & risk assessment |
racer-planner.json |
Planner | Sequencing & execution order |
Run the three archetypes in sequence for the full demo:
- Researcher → "Who hit us?" — KADC adversary intel brief
- Analyst → "Which corridor?" — COA evaluation vs threat posture
- Planner → "Execute." — Drone sequencing execution order
RACER is designed to extend without writing code. Everything is driven by markdown files.
Create a folder under scenarios/ and drop in your context files:
scenarios/
└── your_scenario/
├── scenario.json # metadata: name, description, mission
├── situation.md # what happened
├── threat.md # adversary/environmental context
└── assets.json # resources available
The scenario loader auto-picks up all .md and .json files in the folder — no code changes needed. Then call the API with "scenario": "your_scenario".
Create a .md file under archetypes/:
archetypes/
└── logistician.md
Define three things in the file:
- Persona — who this archetype is and how it reasons
- Task — what it does with the scenario context
- Output format — what structure it returns (e.g.
supply_plan,priority_list)
Then call the API with "archetype": "logistician".
curl -X POST http://localhost:8000/task \
-H "Content-Type: application/json" \
-d '{
"scenario": "your_scenario",
"archetype": "logistician",
"query": "What supplies are critical in the first 6 hours?"
}'No deployment restart needed — archetypes and scenarios are loaded at runtime.