@graphoria/server 0.2.2 → 0.3.0

package/src/subscriptions/types.ts

@@ -2,6 +2,7 @@ import type { ServerWebSocket } from "bun";
 import type { AnalysisResult, SelectionAnalysis, VariableDefinition } from "../analyzeQuery/types";
 import type { GetSchemaReturn } from "../configuration/getSchemas";
 import type { createQueryEventEmitter } from "../utils/event-emitter";
+import type { SessionContext } from "../utils/sessionVariables";
 
 /**
  * Type for the query event emitter instance
@@ -24,7 +25,7 @@ export interface SubscriptionContext {
   ws: ServerWebSocket<unknown>;
   /** Unique subscription ID from the client */
   subscriptionId: string;
-  /** Analyzed GraphQL query */
+  /** Analyzed GraphQL query, with variables and `$session.*` already resolved */
   analysis: AnalysisResult;
   /** The first field being subscribed to */
   field: SelectionAnalysis;
@@ -34,6 +35,8 @@ export interface SubscriptionContext {
   variables: Record<string, unknown>;
   /** Schema and entity information for the current role */
   schemaEntity: GetSchemaReturn;
+  /** The caller this subscription belongs to. Load-bearing: it keys the group. */
+  session: SessionContext;
   /** Shared event emitter for broadcasting updates */
   eventEmitter: QueryEventEmitter;
 }

package/src/subscriptions/utils/polling.ts

@@ -5,6 +5,7 @@ import type { DatabasePoller, QueryEventEmitter } from "../types";
 
 import { executeQuery, executeQueryJSON, generateSQL } from "../../databases";
 import { logger } from "../../logging";
+import { env } from "../../singletons/env";
 
 export interface DatabasePollerConfig {
   analysis: AnalysisResult;
@@ -60,9 +61,11 @@ export const createDatabasePoller = async (
   const firstFieldName = getFirstFieldName(analysis);
   const db = schemaEntity.queriesMap[firstFieldName!]!.db!;
 
-  // Generate SQL queries (data query and hash query)
-  const [[, queryData]] = generateSQL(schemaEntity, analysis, variables);
-  const [[, queryHash]] = generateSQL(schemaEntity, analysis, variables, true);
+  // Generate SQL queries (data query and hash query). A subscription query is
+  // caller-authored, so it carries the same page bounds an HTTP query does.
+  const pageLimits = { defaultPageSize: env.defaultPageSize, maxPageSize: env.maxPageSize };
+  const [[, queryData]] = generateSQL(schemaEntity, analysis, variables, false, pageLimits);
+  const [[, queryHash]] = generateSQL(schemaEntity, analysis, variables, true, pageLimits);
 
   // Get initial hash and send initial data
   let previousHash = await getResultHash(queryHash, db, variableDefinitions, variables);

package/src/types/env.ts

@@ -30,12 +30,21 @@ export const EnvZod = z
     // Boolean flags use stringbool, not coerce.boolean: Boolean("false") === true would flip them on
     CONSOLE_ENABLED: z.stringbool().default(false),
     CONSOLE_ENDPOINT: z.string().default("/_console"),
+    CONSOLE_SESSION_EXPIRES_IN: z.string().default("1h"),
     PREFIX: z.string().default(""),
     CORS_ENABLED: z.stringbool().default(true),
     PRINT_SCHEMAS: z.stringbool().default(false),
     SCHEMAS_OUTPUT_DIR: z.string().default("./.graphoria/schemas"),
     QUERY_ON_RESPONSE: z.stringbool().default(false),
-    MAX_QUERY_DEPTH: z.coerce.number().int().min(0).default(0),
+    MAX_QUERY_DEPTH: z.coerce.number().int().min(0).default(8),
+    DEFAULT_PAGE_SIZE: z.coerce.number().int().min(0).default(100),
+    MAX_PAGE_SIZE: z.coerce.number().int().min(0).default(1000),
+    QUERY_TIMEOUT_MS: z.coerce.number().int().min(0).default(10000),
+    MAX_QUERY_COST: z.coerce.number().int().min(0).default(0),
+    RATE_LIMIT_MAX: z.coerce.number().int().min(0).default(0),
+    RATE_LIMIT_ANONYMOUS_MAX: z.coerce.number().int().min(0).default(0),
+    RATE_LIMIT_WINDOW_MS: z.coerce.number().int().positive().default(60000),
+    RATE_LIMIT_TRUST_PROXY: z.stringbool().default(false),
     AI_ENABLED: z.stringbool().optional(),
     AI_GRAPHQL_ENABLED: z.stringbool().default(true),
     AI_REST_ENABLED: z.stringbool().default(true),
@@ -66,6 +75,10 @@ export const EnvZod = z
     authStrategy: env.AUTH_STRATEGY,
     queryOnResponse: env.QUERY_ON_RESPONSE,
     maxQueryDepth: env.MAX_QUERY_DEPTH,
+    defaultPageSize: env.DEFAULT_PAGE_SIZE,
+    maxPageSize: env.MAX_PAGE_SIZE,
+    queryTimeoutMs: env.QUERY_TIMEOUT_MS,
+    maxQueryCost: env.MAX_QUERY_COST,
     admin: {
       secret: env.ADMIN_SECRET,
       header: env.ADMIN_SECRET_HEADER,
@@ -80,6 +93,12 @@ export const EnvZod = z
       secretKey: env.PASETO_SECRET_KEY,
       publicKey: env.PASETO_PUBLIC_KEY,
     },
+    rateLimit: {
+      max: env.RATE_LIMIT_MAX,
+      anonymousMax: env.RATE_LIMIT_ANONYMOUS_MAX,
+      windowMs: env.RATE_LIMIT_WINDOW_MS,
+      trustProxy: env.RATE_LIMIT_TRUST_PROXY,
+    },
     cache: {
       store: env.CACHE_STORE,
       redisUrl: env.REDIS_URL,
@@ -94,6 +113,7 @@ export const EnvZod = z
     console: {
       enabled: env.CONSOLE_ENABLED,
       endpoint: env.CONSOLE_ENDPOINT,
+      sessionExpiresIn: env.CONSOLE_SESSION_EXPIRES_IN,
     },
     ai: {
       enabled: env.AI_ENABLED,

package/src/utils/rateLimit.ts

@@ -0,0 +1,209 @@
+import { LRUCache } from "lru-cache";
+
+import { logger } from "../logging";
+
+export type ConsumeResult = { allowed: boolean; retryAfterMs: number };
+
+/**
+ * One method, everything per call: a role with its own limit shares the store
+ * with every other role rather than needing an instance of its own.
+ */
+export interface RateLimitStore {
+  consume(
+    key: string,
+    capacity: number,
+    refillPerMs: number,
+    ttlMs: number,
+  ): Promise<ConsumeResult>;
+}
+
+type Bucket = { tokens: number; ts: number };
+
+export type MemoryRateLimitStoreOptions = {
+  now?: () => number;
+  maxKeys?: number;
+};
+
+const DEFAULT_MAX_KEYS = 10_000;
+
+export const createMemoryRateLimitStore = ({
+  now = Date.now,
+  maxKeys = DEFAULT_MAX_KEYS,
+}: MemoryRateLimitStoreOptions = {}): RateLimitStore => {
+  // The bound is load-bearing: an unbounded map keyed by client address is
+  // itself a memory-exhaustion vector. Evicting a bucket only ever gives its
+  // owner a full one, which is what an idle caller would have had anyway.
+  const buckets = new LRUCache<string, Bucket>({ max: maxKeys });
+
+  return {
+    consume: async (key, capacity, refillPerMs, ttlMs) => {
+      const nowMs = now();
+      const bucket = buckets.get(key);
+      const tokens = bucket
+        ? Math.min(capacity, bucket.tokens + (nowMs - bucket.ts) * refillPerMs)
+        : capacity;
+
+      if (tokens < 1) {
+        buckets.set(key, { tokens, ts: nowMs }, { ttl: ttlMs });
+        return { allowed: false, retryAfterMs: Math.ceil((1 - tokens) / refillPerMs) };
+      }
+
+      buckets.set(key, { tokens: tokens - 1, ts: nowMs }, { ttl: ttlMs });
+      return { allowed: true, retryAfterMs: 0 };
+    },
+  };
+};
+
+export type RateLimitRedisClient = {
+  send(command: string, args: string[]): Promise<unknown>;
+};
+
+type RateLimitLogger = { warn(obj: object, msg: string): void };
+
+export type RedisRateLimitStoreOptions = {
+  now?: () => number;
+  log?: RateLimitLogger;
+};
+
+// KEYS[1] = bucket key, ARGV = capacity, refillPerMs, nowMs, ttlMs. Refill,
+// read and write have to happen inside Redis: doing them from here would race
+// between workers, which is the whole reason for reaching for Redis at all.
+const CONSUME_SCRIPT = `
+local b = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
+local tokens = tonumber(b[1]) or tonumber(ARGV[1])
+local ts = tonumber(b[2]) or tonumber(ARGV[3])
+tokens = math.min(tonumber(ARGV[1]), tokens + (tonumber(ARGV[3]) - ts) * tonumber(ARGV[2]))
+local allowed = 0
+if tokens >= 1 then tokens = tokens - 1; allowed = 1 end
+redis.call('HMSET', KEYS[1], 'tokens', tokens, 'ts', ARGV[3])
+redis.call('PEXPIRE', KEYS[1], ARGV[4])
+return { allowed, tostring(tokens) }
+`;
+
+export const createRedisRateLimitStore = (
+  client: RateLimitRedisClient,
+  { now = Date.now, log = logger("rate-limit") }: RedisRateLimitStoreOptions = {},
+): RateLimitStore => {
+  let lastWarnMs: number | undefined;
+
+  return {
+    consume: async (key, capacity, refillPerMs, ttlMs) => {
+      const nowMs = now();
+
+      try {
+        const reply = (await client.send("EVAL", [
+          CONSUME_SCRIPT,
+          "1",
+          key,
+          String(capacity),
+          String(refillPerMs),
+          String(nowMs),
+          String(ttlMs),
+        ])) as [number | string, string];
+
+        const allowed = Number(reply[0]) === 1;
+        const tokens = Number(reply[1]);
+
+        return allowed
+          ? { allowed: true, retryAfterMs: 0 }
+          : { allowed: false, retryAfterMs: Math.ceil((1 - tokens) / refillPerMs) };
+      } catch (error) {
+        // A dead cache must not take the API down, and a dead cache must not
+        // produce a log line per request either — the flood would outlast the
+        // outage.
+        if (lastWarnMs === undefined || nowMs - lastWarnMs >= ttlMs) {
+          lastWarnMs = nowMs;
+          log.warn({ err: error }, "rate limit store unavailable, allowing the request");
+        }
+        return { allowed: true, retryAfterMs: 0 };
+      }
+    },
+  };
+};
+
+export type RateLimitSettings = {
+  max: number;
+  anonymousMax: number;
+  windowMs: number;
+  trustProxy: boolean;
+};
+
+type RoleRateLimit = { rateLimit?: { max: number; windowMs?: number } | undefined };
+
+export type RateLimiter = {
+  check(
+    session: { role?: string | undefined; sub?: string | undefined } | null,
+    address: string | undefined,
+  ): Promise<ConsumeResult>;
+};
+
+export type CreateRateLimiterOptions = {
+  settings: RateLimitSettings;
+  anonymousRole: string;
+  permissions?: Record<string, RoleRateLimit | undefined>;
+  /** A factory is only called once a limit is configured, so a disabled
+   * limiter never constructs a store — or a Redis client. */
+  store?: RateLimitStore | (() => RateLimitStore);
+};
+
+// Attacker-controlled once RATE_LIMIT_TRUST_PROXY is on, and it ends up in a
+// store key, so it is capped before it gets there.
+const MAX_ADDRESS_LENGTH = 64;
+
+export const resolveClientAddress = (
+  req: Request,
+  server: { requestIP(req: Request): { address: string } | null } | undefined,
+  trustProxy: boolean,
+): string | undefined => {
+  if (trustProxy) {
+    const forwarded = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    if (forwarded) return forwarded.slice(0, MAX_ADDRESS_LENGTH);
+  }
+
+  return server?.requestIP(req)?.address;
+};
+
+/**
+ * `undefined` when nothing is configured, so the caller can skip the wrapper
+ * entirely and the shipped default costs nothing per request.
+ */
+export const createRateLimiter = ({
+  settings,
+  anonymousRole,
+  permissions = {},
+  store,
+}: CreateRateLimiterOptions): RateLimiter | undefined => {
+  const configured =
+    settings.max > 0 ||
+    settings.anonymousMax > 0 ||
+    Object.values(permissions).some((permission) => (permission?.rateLimit?.max ?? 0) > 0);
+
+  if (!configured) return undefined;
+
+  const resolvedStore =
+    typeof store === "function" ? store() : (store ?? createMemoryRateLimitStore());
+
+  const limitFor = (role: string) => {
+    const roleLimit = permissions[role]?.rateLimit;
+
+    return {
+      max: roleLimit?.max ?? (role === anonymousRole ? settings.anonymousMax : settings.max),
+      windowMs: roleLimit?.windowMs ?? settings.windowMs,
+    };
+  };
+
+  return {
+    check: async (session, address) => {
+      const role = session?.role ?? anonymousRole;
+      const { max, windowMs } = limitFor(role);
+
+      if (max === 0) return { allowed: true, retryAfterMs: 0 };
+
+      const sub = session?.sub;
+      const key =
+        sub && sub !== "anonymous" ? `rl:${role}:${sub}` : `rl:${role}:ip:${address ?? "unknown"}`;
+
+      return resolvedStore.consume(key, max, max / windowMs, windowMs);
+    },
+  };
+};

package/src/utils/responses.ts

@@ -35,6 +35,16 @@ export class S404 extends ClientResponse {
   }
 }
 
+export class S429 extends ClientResponse {
+  constructor(retryAfterMs: number) {
+    super({ errors: [{ message: "Rate limit exceeded" }] }, { status: 429 });
+
+    // Seconds, and never 0: a caller told to retry immediately retries
+    // immediately, which is the traffic the limit is there to stop.
+    this.headers.set("Retry-After", String(Math.max(1, Math.ceil(retryAfterMs / 1000))));
+  }
+}
+
 export class S500 extends ClientResponse {
   constructor(body?: object | null, init?: ResponseInit) {
     super(body, { ...init, status: 500 });

package/src/ai/README.md

@@ -1,257 +0,0 @@
-# ollama_helper
-
-An LLM-powered database query agent that uses tool-calling to discover a PostgreSQL schema, inspect tables, and execute queries — all from a natural language prompt. It is **cross-LLM**: the same agent runs against Ollama (default, local), OpenAI, DeepSeek, Anthropic, and any OpenAI-compatible endpoint — selected with a single env var.
-
-## How It Works
-
-```
-User prompt
-    │
-    ▼
-┌─────────────────────────────────────────────────┐
-│  createAgent({ tools, systemPrompt, wrap })     │
-│  → (prompt) => Promise<string>                  │
-│                                                 │
-│  Agent loop (ask function)                      │
-│  1. Send systemPrompt + wrap(prompt) to LLM     │
-│  2. LLM responds with tool_calls?               │
-│     ├─ Yes → strip nulls, validate via Zod,     │
-│     │        execute tool, feed result back      │
-│     └─ No  → return final answer                │
-│  3. Repeat until answer or max iters            │
-└─────────────────────────────────────────────────┘
-    │
-    ▼
-Final answer (text only — tool calls hidden)
-```
-
-The agent follows a fixed 4-step discovery workflow for every query:
-
-| Step | Tool              | Purpose                                             |
-| ---- | ----------------- | --------------------------------------------------- |
-| 1    | `list_entities`   | Find relevant database tables by keyword search     |
-| 2    | `describe_entity` | Get column names, types, and relationships          |
-| 3    | `query_data`      | Execute the query using structured JSON (preferred) |
-| 3\*  | `graphql_execute` | Raw GraphQL fallback for complex queries            |
-| 4    | —                 | Present results as a Markdown table                 |
-
-Anti-hallucination guards prevent the model from answering without actually querying data.
-
-## Quick Start
-
-**Prerequisites:** an LLM backend. The default is [Ollama](https://ollama.com) (local, free, no API key) running a tool-capable model. To use a hosted provider instead, set `LLM_PROVIDER` and the matching API key (see [Providers](#providers)).
-
-```bash
-# Install dependencies
-bun install
-
-# Run with the default provider (Ollama) and default prompt
-bun run index.ts
-
-# Custom prompt
-bun run index.ts "how many students have an active subscription?"
-
-# Switch providers via env vars
-LLM_PROVIDER=openai    LLM_MODEL=gpt-4o-mini               OPENAI_API_KEY=sk-...        bun run index.ts "list all events"
-LLM_PROVIDER=deepseek  LLM_MODEL=deepseek-chat             DEEPSEEK_API_KEY=sk-...      bun run index.ts "list all events"
-LLM_PROVIDER=anthropic LLM_MODEL=claude-haiku-4-5-20251001 ANTHROPIC_API_KEY=sk-ant-... bun run index.ts "list all events"
-```
-
-### Using as a library
-
-```typescript
-import { createAgent } from "ollama_helper";
-import { tools } from "./src/tools";
-
-// Bind domain config once — call with just a prompt
-const ask = createAgent({
-  tools,
-  systemPrompt: "You are a database assistant…",
-  wrap: (prompt) => `Database query:\n> ${prompt}`,
-});
-
-const answer = await ask("list contacts grouped by role");
-```
-
-## Environment Variables
-
-| Variable            | Default                  | Description                                                 |
-| ------------------- | ------------------------ | ----------------------------------------------------------- |
-| `LLM_PROVIDER`      | `ollama`                 | Backend: `ollama`, `openai`, `deepseek`, or `anthropic`     |
-| `LLM_MODEL`         | per-provider             | Overrides the provider's default model                      |
-| `OPENAI_API_KEY`    | —                        | Required when `LLM_PROVIDER=openai`                         |
-| `OPENAI_BASE_URL`   | —                        | Optional: any OpenAI-compatible endpoint (Groq, Mistral, …) |
-| `DEEPSEEK_API_KEY`  | —                        | Required when `LLM_PROVIDER=deepseek`                       |
-| `ANTHROPIC_API_KEY` | —                        | Required when `LLM_PROVIDER=anthropic`                      |
-| `OLLAMA_HOST`       | `http://localhost:11434` | Ollama server URL                                           |
-| `OLLAMA_MODEL`      | `gemma4:e2b`             | Ollama model (alias of `LLM_MODEL`, kept for back-compat)   |
-
-Defined in `.env` or inline on the command line.
-
-## Providers
-
-The agent talks to every backend through a small `Provider` interface (`src/providers/`). Two wire formats cover everything:
-
-| Provider         | `LLM_PROVIDER` | Default model               | How it connects                    |
-| ---------------- | -------------- | --------------------------- | ---------------------------------- |
-| Ollama (default) | `ollama`       | `gemma4:e2b`                | Native `/api/chat`, local, no key  |
-| OpenAI           | `openai`       | `gpt-4o-mini`               | `openai` SDK                       |
-| DeepSeek         | `deepseek`     | `deepseek-chat`             | `openai` SDK (OpenAI-compatible)   |
-| Anthropic        | `anthropic`    | `claude-haiku-4-5-20251001` | `@anthropic-ai/sdk` (Messages API) |
-
-Because the OpenAI adapter is just a `baseURL` + key, **any OpenAI-compatible endpoint** (Groq, Mistral, Together, a local `/v1` server) works by pointing `OPENAI_BASE_URL` at it — no new code. Adding a first-class provider is one entry in the registry in `src/providers/index.ts`.
-
-The agent loop and anti-hallucination guards are provider-agnostic; each adapter only translates the normalized message/tool-call history to and from its provider's wire format.
-
-## Recommended Ollama Models
-
-| Model          | Size   | Quality | Notes                                                                                         |
-| -------------- | ------ | ------- | --------------------------------------------------------------------------------------------- |
-| **gemma4:e2b** | 7.2 GB | ★★★★★   | **Default.** Native function-calling, built for agentic workflows. Google-recommended params. |
-| gemma4:e4b     | 9.6 GB | ★★★★★   | Stronger reasoning, heavier. Same family, better accuracy.                                    |
-| qwen3.5:2b     | 2.7 GB | ★★★★☆   | Good budget option. Fast, decent tool use.                                                    |
-| llama3.2       | 2.0 GB | ★★☆☆☆   | Works but hallucinates more. Use `OLLAMA_MODEL=llama3.2` to test.                             |
-
-Each model family gets optimal sampling parameters automatically (temperature, top_p, top_k) based on vendor recommendations.
-
-## Project Structure
-
-```
-ollama_helper/
-├── index.ts                  # Library barrel — exports ask, createAgent, AgentConfig
-├── .env                      # Environment variables (OLLAMA_MODEL, OLLAMA_HOST)
-├── package.json
-├── tsconfig.json
-└── src/
-    ├── types.ts              # Normalized Message/ToolCall + Provider + Tool interfaces
-    ├── providers/
-    │   ├── index.ts          # getProvider() — selects the backend from LLM_PROVIDER
-    │   ├── ollama.ts         # Native /api/chat adapter + model presets (default)
-    │   ├── openai.ts         # OpenAI-compatible adapter (OpenAI, DeepSeek, …)
-    │   └── anthropic.ts      # Anthropic Messages API adapter
-    ├── tools.ts              # 4 tool definitions (Zod schemas + mock executors)
-    └── agent.ts              # Agent loop: ask() + createAgent() factory
-```
-
-## API
-
-### `createAgent(config: AgentConfig): (prompt: string) => Promise<string>`
-
-Pre-configure an agent with tools, system prompt, and a prompt wrapper. Returns a single-argument function — call it with any prompt string.
-
-```typescript
-import { createAgent } from "ollama_helper";
-
-const ask = createAgent({
-  tools: [...],                              // Tool[] — Zod-based tool definitions
-  systemPrompt: "You are a helpful agent.",  // System-level instruction to the LLM
-  wrap: (p) => `User query:\n> ${p}`,        // Wraps the raw prompt into the user message
-});
-
-const answer = await ask("list all contacts grouped by role");
-```
-
-### `ask(prompt, tools, systemPrompt, wrap): Promise<string>`
-
-Full-control entry point. Same as `createAgent` but without pre-binding — pass all 4 arguments per call.
-
-```typescript
-import { ask } from "ollama_helper";
-
-const answer = await ask(
-  "list contacts grouped by role",
-  tools,
-  "You are a database assistant.",
-  (p) => `Query: ${p}`,
-);
-```
-
-### `AgentConfig`
-
-| Field          | Type                          | Description                                            |
-| -------------- | ----------------------------- | ------------------------------------------------------ |
-| `tools`        | `Tool[]`                      | Zod-based tool definitions (schema + executor)         |
-| `systemPrompt` | `string`                      | System-level instruction sent to the LLM               |
-| `wrap`         | `(content: string) => string` | Transforms the user prompt into the final user message |
-
-### `Tool`
-
-```typescript
-interface Tool<TSchema extends z.ZodTypeAny> {
-  name: string; // Tool name (must match what the LLM calls)
-  description: string; // Description sent to the LLM
-  schema: TSchema; // Zod schema — auto-converted to JSON Schema
-  execute: (args: z.infer<TSchema>) => Promise<unknown>; // Typed executor
-}
-```
-
-JSON Schema is auto-generated via `z.toJSONSchema(tool.schema)`. The framework automatically strips `null` values from LLM arguments (common with small models) before Zod validation. Use the exported `jsonCoerce` helper for fields that may arrive as stringified JSON arrays/objects.
-
-```typescript
-import { z } from "zod";
-import { jsonCoerce } from "./src/tools";
-
-const mySchema = z.object({
-  columns: jsonCoerce(z.array(z.string())).optional(), // Handles "[\"id\"]" → ["id"]
-  filters: jsonCoerce(z.record(z.string(), z.unknown())).optional(),
-});
-```
-
-## Tools
-
-The agent exposes 4 tools to the LLM. Each is defined as a `Tool` object with a Zod schema and executor:
-
-| Tool              | Description                                                                      |
-| ----------------- | -------------------------------------------------------------------------------- |
-| `list_entities`   | Search for database tables by keyword or category                                |
-| `describe_entity` | Get column metadata, relationships, and data types for a table                   |
-| `query_data`      | Execute a query using structured JSON (preferred for all list/aggregate queries) |
-| `graphql_execute` | Execute a raw GraphQL query (fallback for complex/nested queries)                |
-
-**`query_data` input format:**
-
-```json
-{
-  "entity": "contacts",
-  "operation": "aggregate",
-  "groupBy": ["role"],
-  "columns": ["id", "first_name", "last_name"],
-  "filters": { "deleted_at": { "is_null": true } },
-  "limit": 50
-}
-```
-
-Filter operators: `eq`, `neq`, `like`, `ilike`, `gt`, `gte`, `lt`, `lte`, `is_null`.
-
-## Anti-Hallucination Measures
-
-The agent employs multiple layers to prevent the LLM from fabricating data:
-
-1. **Zod validation** — All tool arguments validated before execution; invalid args → error fed back to LLM for self-correction
-2. **Null stripping** — `null` values for optional fields (common LLM mistake) automatically stripped pre-parse
-3. **JSON coercion** — Stringified JSON arrays/objects auto-parsed via `jsonCoerce` helper
-4. **Temperature control** — Model-specific presets (e.g., temp 0 for llama3.2 to suppress creativity)
-5. **Guard clause** — If the model tries to answer without calling `query_data` or `graphql_execute`, a corrective nudge is injected and the loop retries
-6. **Negative constraints** — Prompts explicitly forbid fabrication: _"NEVER fabricate, invent, or guess query results"_
-
-## Mock Tools
-
-When a real Graphoria server is not available, the tools return hardcoded mock data mirroring the capoeira group management schema:
-
-- **5 tables:** contacts, student_profiles, classes, payments, events
-- **18 contacts** with roles: 12 students, 1 master, 2 guardians, 3 guests
-- **Full column metadata** for the contacts table (11 columns including soft-delete `deleted_at`)
-
-To replace mocks with real server calls, update the executors in `src/tools.ts` to use `fetch()` against the Graphoria REST/GraphQL endpoints.
-
-## Design Decisions
-
-- **`createAgent` factory** — Pre-bind domain config (tools, system prompt, wrap); clean `ask(prompt)` API for callers
-- **`ask()` for full control** — 4 positional params when callers need per-call variations
-- **Zod schemas for tools** — `z.toJSONSchema()` auto-generates JSON Schema parameters; `z.infer` gives type-safe executor args; no hand-written JSON Schema
-- **`stripNulls` applied automatically** — LLMs pass `null` for optional fields; stripped pre-parse so callers write plain Zod schemas
-- **`jsonCoerce` opt-in helper** — Small LLMs stringify arrays/objects; opt-in per-field coercion
-- **Non-streaming only** (`stream: false`) — simpler loop logic; no need to buffer partial tool_calls across chunks
-- **JSON query tool over raw GraphQL** — structured JSON has far fewer syntax failure modes for LLMs than raw GraphQL string construction
-- **Max 10 iterations** — safety valve to prevent infinite tool-calling loops
-- **Bun runtime** — native fetch, zero-config TypeScript, fast startup