AI Protocol Architecture

core.ai is the LLM abstraction layer for the UNVRSL platform. It provides a unified conversation API with provider abstraction, tool use, transparent execution tracing, streaming, cost tracking, and media handling.

> Status: Architecture defined. Implementation pending.

Why core.ai Exists

LLM providers have incompatible APIs, different message formats, different streaming protocols, and different pricing models. Without abstraction, every app that uses AI needs to handle provider differences, manage API keys, track costs, and build conversation storage from scratch.

core.ai solves this by providing:

• One API — apps talk to core.ai, not directly to OpenAI/Anthropic/Google


• Provider abstraction — switch providers without changing app code


• Conversation persistence — conversations, messages, traces, and media stored centrally


• Tool use — server-side tool execution with a unified tool call/result model


• Execution tracing — every step between question and answer is visible and expandable


• Cost tracking — per-call cost tracking with real USD cents, integrated with core.auth quotas


• Media pipeline — uploads via core.storage, processing via core.hypermedia

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐

│                         Client App                              │

│                                                                 │

│  Chat UI with trace timeline:                                   │

│  ┌──────────┐                                                   │

│  │ User msg │                                                   │

│  └────┬─────┘                                                   │

│       ▼                                                         │

│  ┌──────────────────┐                                           │

│  │ 💭 Thinking  [▸] │  ← expandable trace card                  │

│  └──────────────────┘                                           │

│  ┌──────────────────┐                                           │

│  │ 🔧 Tool call [▸] │  ← expandable trace card                  │

│  └──────────────────┘                                           │

│  ┌──────────────────┐                                           │

│  │ ⚡ LLM call  [▸] │  ← expandable trace card                  │

│  └──────────────────┘                                           │

│  ┌──────────┐                                                   │

│  │ Assistant│                                                   │

│  └──────────┘                                                   │

└─────────────────────────┬───────────────────────────────────────┘

                          │ SSE

                          ▼

┌─────────────────────────────────────────────────────────────────┐

│                          core.ai                                │

│                                                                 │

│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐ │

│  │ Conversations │  │  Messages    │  │  Trace Events         │ │

│  │  & Presets    │  │  (LLM ctx)   │  │  (UI display)         │ │

│  └──────────────┘  └──────────────┘  └───────────────────────┘ │

│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐ │

│  │  API Calls   │  │ Cost Ledger  │  │  Tool Registry        │ │

│  │  (audit)     │  │  (billing)   │  │  (available tools)    │ │

│  └──────────────┘  └──────────────┘  └───────────────────────┘ │

│                                                                 │

│  ┌──────────────────────────────────────────────────────────┐  │

│  │  Provider Adapters                                       │  │

│  │  OpenAIAdapter │ AnthropicAdapter │ GoogleAdapter         │  │

│  └──────────────────────────────────────────────────────────┘  │

│                           │                                     │

└───────────────────────────┼─────────────────────────────────────┘

                            │

              ┌─────────────┼─────────────┐

              ▼             ▼             ▼

          ┌──────┐    ┌──────────┐  ┌─────────┐

          │OpenAI│    │Anthropic │  │ Google  │

          └──────┘    └──────────┘  └─────────┘

Data Tables

Core Tables

Table	Purpose	Sent to LLM?

conversations	Container, settings, defaults	—
messages	What was said (user, assistant, system, tool)	✅
trace_events	How it was produced (thinking, tool calls, errors)	❌
api_calls	One row per LLM request (tokens, latency, status)	❌
cost_ledger	Billing per api_call (credits + real USD cents)	❌
media	File attachments per message	❌

Supporting Tables

Table

Purpose

system_prompts	Prompt file catalog (filesystem-indexed)
skills	Developer-facing prompt + model configs
presets	User-facing conversation templates
tools	Tool registry, per project

Messages are the canonical conversation — they're what you send to the provider to rebuild context. Trace events are the story of how each message was produced — they're for the UI and debugging. API calls are the audit trail. Cost ledger is the financial record.

Pages

• Provider Model — Providers, adapters, internal message format, streaming


• Database Schemas — Full SQL for all five tables


• Conversation Flow — Request lifecycle, tool use loop, trace events, SSE protocol


• Cost & Billing — Cost ledger, USD cents, quota integration

Design Principles

• Messages are conversation state. Traces are process metadata. Never mix them. Messages get sent to the LLM. Traces never do.


• One API call = one cost record. Not one per "turn." Tool use creates multiple API calls per user message, each with real cost.


• User messages are not free. Every message in the conversation history is input tokens. Cost belongs to the API call, not to a specific message role.


• Keep originals. Media compression produces derivatives — never delete the original.


• Tool calls are part of the assistant message. Tool results are separate messages. Traces capture the full detail.


• Transparency by default. Every step between question and answer is captured and available to the user as an expandable trace card.


• Real cost, always. The cost ledger tracks real USD cents per cost category (input, output, thinking, cached) for auditing, not just platform credits.

Presets vs Skills

Presets

Skills

Audience	End users	Developers / platform
What they do	Pre-fill conversation with avatar, description, pre-prompt, prompt template	Combine system prompt with model config
Storage	presets table	skills table
Pre-prompt	Folded into system prompt at conversation creation	Part of the system prompt file

System Prompts

System prompts are stored as files on the filesystem, indexed in a database table for discovery. The preset's pre_prompt is folded into the system prompt at conversation creation time — it is NOT a separate message. One system prompt per conversation.

API Key Management

Provider API keys are platform-owned, not user-owned (no BYOK). Stored in config file or env vars. Never in the database. Never exposed via API. Users never see or manage provider keys.

Relationship to Other Services

core.ai

    ├── uses core.auth for user sessions and quota enforcement

    ├── uses core.storage for media file storage (originals preserved)

    ├── uses core.hypermedia for media compression/conversion

    ├── uses core.assets for UI components (chat interface)

    └── is accessed via core.console (API gateway routing)

Related

• Auth Architecture — User sessions, quota system, credit rates


• Storage Architecture — Media file storage


• Hypermedia Pipeline — Media compression/conversion


• Console Architecture — API gateway routing