AkurAI-Framework / site/frontend/llms.txt

Latest change 631417472adebacf9be16c712af89ca5d8a25c28 - Add RustAgent agent OS UI contract by Ólafur Búi Ólafsson

# AkurAI/Framework

> A single-binary, pure-Rust, zero-runtime-dependency, no-build full-stack web framework. The shipped binary links no external crates — HTTP, JSON, an embedded crash-safe B+tree database, a SQL engine, server-side templates, Markdown, an atomic CSS engine, an auto-generated REST API with semantic search, and a built-in AI chat UI are all written from scratch on the Rust standard library. The frontend is hand-written native ES modules: no bundler, no npm, no TypeScript, no build step.

Use this file to understand what the framework is, how its pieces fit together, and — in particular — its AI component library (a native-ESM port of assistant-ui + tool-ui). Each link below points to a focused documentation page. Live site: https://akurai-framework.olibuijr.com

Key facts for an LLM working with this framework:
- **No build step, no React.** Pages are SSR templates (`{{ }}`, `{% if %}`, `{% for %}`, `{% include %}`); client interactivity is plain ES modules. Do not introduce React, a bundler, npm, or TypeScript.
- **Pure std, zero deps in the binary.** New backend features are pure-Rust std-only crates in `crates/`. Network I/O is plain HTTP (no TLS in std — TLS terminates at the nginx edge); HTTPS client URLs are rejected.
- **Data is declarative.** Declare collections in `backend/collections.toml` and the server mounts a full REST API (`/api/collections/<name>/records`) with validation, relations, file uploads, and `?search=` semantic search — no handler code.

## Guide
- [Getting started](https://akurai-framework.olibuijr.com/docs/getting-started): project layout, `akurai new`/`serve`/`dev`.
- [Architecture](https://akurai-framework.olibuijr.com/docs/architecture): the crates and how they compose.
- [CLI & dev server](https://akurai-framework.olibuijr.com/docs/cli): commands, live-reload, `akurai update`.
- [Roadmap & status](https://akurai-framework.olibuijr.com/docs/roadmap): what ships today vs. what's planned.

## Building an app
- [Routing](https://akurai-framework.olibuijr.com/docs/routing): declarative `routes.json`, `:param`/`*wildcard`.
- [Layouts](https://akurai-framework.olibuijr.com/docs/layouts) and [Data loaders](https://akurai-framework.olibuijr.com/docs/loaders).
- [Forms & actions](https://akurai-framework.olibuijr.com/docs/forms): POST bodies, validation, Post/Redirect/Get.
- [Templates & Markdown](https://akurai-framework.olibuijr.com/docs/styling), [Reactivity](https://akurai-framework.olibuijr.com/docs/reactivity), [Islands & hydration](https://akurai-framework.olibuijr.com/docs/islands), [SPA router](https://akurai-framework.olibuijr.com/docs/spa-router).
- [Static generation (SSG/ISR)](https://akurai-framework.olibuijr.com/docs/ssg), [Internationalisation](https://akurai-framework.olibuijr.com/docs/i18n), [Error & loading boundaries](https://akurai-framework.olibuijr.com/docs/boundaries).
- [Middleware](https://akurai-framework.olibuijr.com/docs/middleware), [SEO](https://akurai-framework.olibuijr.com/docs/seo), [Asset pipeline](https://akurai-framework.olibuijr.com/docs/assets).

## Data engine
- [Storage](https://akurai-framework.olibuijr.com/docs/storage): crash-safe copy-on-write B+tree, atomic WAL-free commits.
- [SQL](https://akurai-framework.olibuijr.com/docs/sql) and [SQL executor](https://akurai-framework.olibuijr.com/docs/sql-executor): from-scratch CREATE/INSERT/SELECT/UPDATE/DELETE over the B+tree.
- [Collections & auto-API](https://akurai-framework.olibuijr.com/docs/auto-api): `collections.toml` → REST CRUD + `/api/_meta`.
- [Semantic search](https://akurai-framework.olibuijr.com/docs/semantic-search): `?search=` ranks records by embedding similarity (substring fallback).
- [File uploads](https://akurai-framework.olibuijr.com/docs/uploads), [Typed client SDK](https://akurai-framework.olibuijr.com/docs/client-sdk), [Admin UI](https://akurai-framework.olibuijr.com/docs/admin), [Auth & sessions](https://akurai-framework.olibuijr.com/docs/auth).

## AI components (assistant-ui + tool-ui, ported to native ESM)
A production-grade AI chat UI and tool-result component library, reimplemented as no-build ES modules on the framework's own design system. Provenance: a 1:1 port (in spirit, not code) of [assistant-ui](https://github.com/assistant-ui/assistant-ui) and [assistant-ui/tool-ui](https://github.com/assistant-ui/tool-ui) — no React, no Tailwind, no Zod.

- [AI components overview](https://akurai-framework.olibuijr.com/docs/ai-components): what's included + the framework support (LLM client, streaming assistant endpoint, schema validator).
- [Using AI components (guide)](https://akurai-framework.olibuijr.com/docs/ai-usage): end-to-end — configure an LLM, mount a chat, register tool components, worked examples.
- [Live component gallery](https://akurai-framework.olibuijr.com/ai-components): every tool component rendered live from its example payload.
- [Assistant API](https://akurai-framework.olibuijr.com/docs/assistant-api): `POST /api/assistant` streams tokens and tool calls over SSE (`AKURAI_LLM_URL`/`AKURAI_LLM_MODEL`, OpenAI-compatible, plain HTTP).
- [Chat primitives](https://akurai-framework.olibuijr.com/docs/chat): Thread, Message, Composer, ActionBar — composable, streaming.
- [Generative UI & tool-call runtime](https://akurai-framework.olibuijr.com/docs/generative-ui): a tool payload is matched against a component's schema and rendered inline; mismatches fall back to JSON; interactions persist as "receipts" back to the assistant. Each component is an ES module exporting `def = { name, category, title, match(payload), render(payload, ctx), example }`.
- [AkurAI-RustAgent agent OS UI](https://akurai-framework.olibuijr.com/docs/agent-os-ui): the adapter contract for turning RustAgent/Hermes-style channels, confirmations, questions, tool calls, edit previews, artifacts, and durable workspace state into the framework's assistant-ui/tool-ui components.
- [Payload schemas](https://akurai-framework.olibuijr.com/docs/schema): the std-only JSON-shape validator used to match payloads to components.
- Tool component catalog (30+ components in six categories), each with payload shapes + examples:
  [Display](https://akurai-framework.olibuijr.com/docs/ai-display) ·
  [Artifacts](https://akurai-framework.olibuijr.com/docs/ai-artifacts) ·
  [Content](https://akurai-framework.olibuijr.com/docs/ai-content) ·
  [Input](https://akurai-framework.olibuijr.com/docs/ai-input) ·
  [Progress & Confirmation](https://akurai-framework.olibuijr.com/docs/ai-progress) ·
  [Media](https://akurai-framework.olibuijr.com/docs/ai-media).

## Reference
- [API reference](https://akurai-framework.olibuijr.com/docs/api-reference): the built-in `/api/*` surface.
- [Breaking changes](https://akurai-framework.olibuijr.com/docs/breaking-changes) and [Changelog](https://akurai-framework.olibuijr.com/changelog).
- Source: https://github.com/olibuijr/AkurAI-Framework

## How to extend it (for an AI agent making changes)
- Add a tool-result component: create `site/frontend/ai/components/<category>/<name>.js` exporting a `def` (see Generative UI); it auto-appears in the gallery and is matched by the runtime.
- Build an agent OS surface: keep channel identity explicit (`analysis`, `commentary`, `final`, `tool_call`, `approval`, `question`, `edit`, `artifact`) and route interactive answers through `ctx.sendReceipt` / `toolui:receipt`, not plain chat text.
- Add a backend capability: a new pure-`std` crate in `crates/` (zero deps), wired into `crates/cli`. Ship its `/docs/<feature>.md` + a `docs_nav` entry in the same change, plus a changelog entry; document any breaking change in `/docs/breaking-changes`.
- Contributor map: `AGENTS.md` (domain-split: `AGENTS_CRATES.md`, `AGENTS_DATA.md`, `AGENTS_FRONTEND.md`, `AGENTS_DEPLOY.md`, `AGENTS_TESTING.md`, `AGENTS_DOCS.md`).