Atharias Docs

Integration notes for the current simulation and key-management routes in this repo.

Quick Start

1

Sign in or create an account

Atharias is currently running as a closed beta. Open `/login` to sign in or manage an existing account, or visit `/waitlist` to request access. Once approved, open `/dashboard` to create and manage your trial keys.

2

Inspect or create a key with your session

await fetch("/api/v1/keys", {
  method: "GET",
  credentials: "include",
  cache: "no-store"
})

→ {
  "keys": [
    {
      "key": "ssim_...",
      "email": "you@company.com",
      "credits": 7500,
      "total_tokens_used": 0,
      "created_at": "..."
    }
  ]
}
3

Run a simulation

curl -X POST http://localhost:3000/api/v1/simulate \
  -H "x-api-key: ssim_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_id": "toxic_gamers",
    "platform": "twitter",
    "input": "We are proud to announce NFTs in our next game!"
  }'

→ {
  "simulation_id": "uuid",
  "status": "queued",
  "expected_messages": 1000,
  "simulation_rounds": 10,
  "reserved_credits": 1000,
  "progress_messages": 0,
  "poll_url": "/api/v1/simulate?id=uuid"
}
4

Poll for progress

Simulations now run through the queue and return immediately. Each run can span multiple rounds, with every persona getting a chance to post in every round. Poll the same route with the `simulation_id` until the status becomes `completed` or `failed`.

curl http://localhost:3000/api/v1/simulate?id=uuid \
  -H "x-api-key: ssim_your_key"

→ {
  "simulation_id": "uuid",
  "status": "running",
  "progress_messages": 25,
  "expected_messages": 1000
}
5

Run a worker

The API now enqueues jobs quickly, but they only execute when a worker is running. In development or self-hosted environments, start at least one hot worker process.

npm run worker

Reference

Audiences
toxic_gamersHardcore gaming community
genzGen Z social media users
engineersSoftware engineering community
small_townSmall town community
company_internalCorporate internal comms
Platforms
twitterShort-form, hostile, 280 char limit
slackCorporate, passive-aggressive
redditLong-form, anonymous

Architecture

AGENTS.md

AI assistant context for the Social Simulation API (B2B Infrastructure).

Project

  • Goal: API for predictive Agent-Based Modeling (ABM) of social discourse.
  • Stage: "Wizard of Oz" Hackathon MVP (Pre-Seed)
  • Stack: Next.js 16 (App Router), TypeScript, Supabase, OpenRouter (Llama 3.1 8B)
  • Core IP: Extracting psychographic "Agent DNA" and running multi-agent simulations using uncensored local/cloud LLMs to predict social backlash.

Domain Terminology

  • Agent DNA (Universal Persona Matrix): A JSON object defining a synthetic agent's personality (e.g., reactivity baseline, brand affinity, sophistication, core values).
  • The Ghost Shift: The latent opinion shift of "lurkers" (the silent majority). The model tracks the specific "action threshold" where a lurker becomes angry enough to post.
  • Environment: The context of the simulation (e.g., twitter for short-form hostile, slack for corporate, reddit for long-form anonymous).
  • Batteries-Included Audiences: Pre-computed static JSON files containing Agent DNA for specific demographics stored in train/ and seeded to the audiences table.

Structure

social-sim-api/
├── app/
│   ├── layout.tsx              # Dark theme layout with nav
│   ├── page.tsx                # Landing page with hero + mock terminal
│   ├── globals.css             # Tailwind base styles
│   ├── keys/page.tsx           # API key generation (client component)
│   ├── docs/page.tsx           # Documentation (server component)
│   └── api/v1/
│       ├── simulate/route.ts   # POST - streaming NDJSON simulation
│       └── keys/route.ts       # POST - API key creation
├── lib/
│   ├── env.ts                  # Zod-validated environment variables
│   ├── auth.ts                 # API key validation + credit decrement
│   ├── schemas.ts              # Zod schemas (Persona, SimulateInput, CreateKey)
│   ├── supabase/
│   │   ├── server.ts           # Service-role Supabase client
│   │   └── browser.ts          # Anon/publishable Supabase client
│   └── simulation/
│       ├── types.ts            # SimulationState, AgentMessage types
│       ├── prompts.ts          # Platform-specific system prompts
│       ├── llm.ts              # OpenRouter LLM client
│       └── engine.ts           # AsyncGenerator state machine (10 rounds)
├── supabase/
│   └── migrations/
│       └── 001_initial_schema.sql  # audiences, api_keys, simulations tables
├── scripts/
│   └── seed.ts                 # Seed audiences from train/ JSON files
├── train/                      # 5 persona JSON files (~150 agents total)
└── .env                        # Environment variables (gitignored)