@athenox/talos/docs/reference.md

Talos: a backend you describe instead of write. Declare a schema, write the rules in plain language, map URLs to sentences; a small built-in model turns them into query plans.

# Reference

## The app

| export | |
|---|---|
| `defineApp({ schema, prompt, store?, seed?, actions?, checkVocab?, telemetry? })` | returns `{ run, decide, execute, route, feedback, instanceId, store, ready, telemetry, schema, prompt }` |
| `app.run(sentence, ctx, shape?)` | model + execution: `{ plan, status, result, callId, ms }` |
| `app.route(template, shape?)` | `(params, ctx, shape?) => answer`, compiled once |
| `app.decide(sentence, ctx, ops?)` | the plan only: `{ plan, ms, refuseP, callId }` |
| `app.execute(plan, ms, sentence, ctx, shape)` | run a plan |
| `app.feedback(callId, { text?, rating? })` | see [telemetry.md](telemetry.md) |
| `app.ready` | resolves `{ file }` once Talos's own database is open |
| `authorise(plan, schema, role)` | the permission check, on its own |
| `planText(plan)` | a plan as one line |
| `modelInfo()` | versions, parameters, vocabulary size, operations |
| `addSurfaceForms(forms)`, `checkVocabulary(schema)` | the model's words |
| `slugify(text)` | |

## HTTP (h3)

| export | |
|---|---|
| `defineRoutes(app, table, { guards?, defaults?, passthrough? })` | see [routes.md](routes.md) |
| `sentenceRoute(app, template, options)` | one route as an h3 handler |
| `accounts(options)` | see [accounts.md](accounts.md) |
| `serveFiles(dir, { guard?, maxAge? })` | stored files |
| `rateLimit({ max, windowMs, methods?, message? })` | per address, 429 over the limit |
| `feed('rss' \| 'sitemap' \| 'sitemap-news', { rows, item, title?, site?, extra?, days? })` | feeds and sitemaps from rows |
| `camelRow(row)` | `created_at` → `createdAt` |
| `useSession(event)` | a minimal cookie session, if you have none |

## Databases

| export | |
|---|---|
| `sqliteStore(db)` | Node's `DatabaseSync` or better-sqlite3 |
| `mysqlStore(pool)` | a mysql2/promise pool (MySQL, MariaDB) |
| `localStore(schema, { file?, seed? })` | Talos's own database, what `defineApp` uses without `store` |
| `fromDrizzle(schema, extra?)` | Talos tables from a Drizzle schema: model-friendly names, defaults, converters; `extra` adds or overrides per table (`false` leaves one out) |
| `syncSchema(store, drizzleSchema, { seed? })` | create missing tables and columns (defaults, foreign keys in dependency order), insert seed rows |
| `hashPassword(pw)`, `verifyPassword(pw, hash)` | scrypt, constant-time compare |

## Data in and out

| export | |
|---|---|
| `parseCsv(text)` | comma, semicolon or tab; quotes; a BOM |
| `toCsv(rows, columns, sep?)` | `columns`: a list, or `{ column: 'Header' }` |
| `importCsv(text, { map, key?, exists?, write, update?, check? })` | rows mapped by header aliases, deduplicated on `key`: `{ total, inserted, updated, skipped, errors: [{ line, reason }] }` |
| `connector({ url, map, found?, headers?, timeoutMs?, cacheMs? })` | an external JSON API read into your fields |

## Meaning

| export | |
|---|---|
| `embedText(text)`, `cosine(a, b)`, `hasEmbedder()` | the text embedder |
| `classify(text, labels, top?)` | the closest label |
| `find(rows, options)`, `rank(...)`, `similar(rows, options)` | the rankers behind `find`, `recommend`, `similar` |
| `useImages(sharp)`, `processImage(buffer, options)` | image processing |

## Types

`Table`, `Schema`, `Fn`, `Actions`, `Ctx`, `Shape`, `Plan`, `Store`,
`RouteOptions`, `AccountsOptions`, `FindOptions`, `RecommendOptions`,
`ImageOptions`, `TelemetryOptions`, `FeedItem`.