Data model

A tool is a callable function, given to the model as a tool-schema (not a prompt). The catalog is open — a registry of types (platform presets + the organization's own class, a mirror of the connectors): the list is a live registry, this table holds the state by name (no row = the type is off, defaults), a row is created lazily. v1 seeds two read-only presets — web_search and fetch_url, both off. Admission is two independent surfaces: chat_enabled (visible to chat) and agents_allowed (available for agents to select); a tool is active as long as it is given to at least one. The agent's selection itself is the agent_tools link in Agent Engine; the runtime filters it by the current agents_allowed, and removal → the agent falls back to the KS core (graceful degradation). Non-secret configuration (the web_search provider, options) lives in config, edited by the admin on the screen, not by a config file; the secret is in credential_enc, not in config: like the ai_providers and SMTP keys, only the is_set flag leaves outward. status / last_check_at hold the result of the health check — by the same device as ai_providers.

The ORM models are in the ai_foundation/models.py package (code convention — one package per module), not in admin: the assigned models are read by the AI consumers Harvester (embed), Knowledge Store (re-embedding), Query Engine (RAG) and Agent Engine — four consumers, not just Admin. Admin provides CRUD and screens; the dependencies go toward core — with no cycles.

The platform ships its own local embeddings runtime — a separate docker-compose service (OpenAI-compatible, model-agnostic), brought up on make up alongside the backend; the container is lightweight and doesn't pull ML dependencies into the API image. Weights are not downloaded at install: the runtime pulls them lazily — on model assignment (and immediately warms it up without waiting for the first request), into a cache volume. Until selected, the embedder takes neither disk nor memory, and so it doesn't limit the deploy. The migration seeds the is_system provider Platform (non-deletable, base_url pointing to the internal service, no key) and the catalog of built-in models — selectable (is_enabled=true) but not loaded. The set is defined by the seed, not the screens (the first iteration — bge-m3 and Qwen3-Embedding-0.6B, both 1024-dimensional); the wireframes reference them only as examples. There is no default assignment: the model_assignments.harvester_embedding row does not exist at the start, and Harvester won't start ingesting without an assignment — Admin must assign an embedding model (built-in or their own) before the first ingest. The reason is hard: the choice fixes the dimension N of the chunks.embedding column, and a later change is a mass re-embedding (with a different N — a schema migration). The default is deliberately empty: neither a model nor its weight is imposed by the installation. How this service handles load streams and scales (v1 → v2) is in the embeddings runtime.

Parameters set by the model itself — the vector dimension (embedding_dim), the window cap (max_input_tokens), the required prefix (instruction_prefix) — live in the model's meta, not in the consumer's config (no hardcoding): Harvester's chunker reads the cap from there, KS takes the embedding_dim of the assigned embedding model and provisions halfvec(N). The built-in models are seeded with their own intrinsics — bge-m3: { embedding_dim: 1024, max_input_tokens: 8192 }, Qwen3-Embedding-0.6B: { 1024, 32768 }. A cloud model's embedding_dim isn't returned by discovery, so the Admin declares it when adding the model; a model without a declared dimension — or one that doesn't match the provisioned halfvec(N) — is refused at assignment (409), before any re-embedding starts.

model_usage accumulates requests / tokens / cost by (model · function · day), not an event-log per request. The budget threshold is an instance setting (ai_monthly_budget + ai_budget_alert_enabled) and lives not here but in platform_settings, next to maintenance_mode: the admin enters the amount by hand and turns it on with a toggle (a CHECK prevents enabling the alert without an amount) on the AI usage screen, in the shared home of limits. On reaching the threshold, a Budget notification is raised — the channel is held by the notifications module. The week / month / year usage panorama on the same screen is a derived SUM over the period, without a separate counter table. How the accounting works end to end is in the usage business logic.