ARIEL Contracts#
ARIEL is integrated into Osprey as a dedicated MCP server
(osprey.mcp_server.ariel) that exposes the logbook search service to the
agent layer through a set of specialized tools. When a user asks a question
like “What happened with the RF cavity last week?”, the OSPREY agent selects
the appropriate ARIEL MCP tool based on the query type, which invokes the
ARIELSearchService and returns structured results that the agent uses to
produce a cited answer. This page is the reference for the contracts that
integration rests on: the MCP tools, the search result structure, the service
factory, the capabilities endpoint the web interface reads, and the database
schema every entry is stored in.
Integration Architecture#
The flow begins when the OSPREY agent determines that a user query involves
historical logbook data. It selects from ARIEL’s specialized MCP tools based
on the query type — for example, keyword_search for exact-match lookups,
semantic_search for conceptual queries, or browse for exploring recent
entries. Each tool builds the appropriate request and routes it through the
ARIELSearchService. Results are returned directly to the agent, which
uses them to generate a cited response.
ARIEL MCP Tools#
ARIEL exposes the following tools through its dedicated MCP server. The OSPREY agent selects the appropriate tool based on the user’s query.
Tool |
Purpose |
|---|---|
|
Full-text keyword search across logbook entries |
|
Vector similarity search using embeddings |
|
Keyword and semantic ranking combined, with optional query expansion and reranking (offered when the hybrid module is enabled) |
|
Direct SQL queries against the logbook database, as its SELECT-only
login (not offered when the |
|
Browse entries with pagination and filters |
|
Get distinct values for a filterable field (authors or source systems) |
|
Check ARIEL service health and configuration |
|
Publish an existing ARIEL entry to the facility logbook |
|
List available search capabilities and their status |
|
Retrieve a single entry by ID |
|
Batch retrieve multiple entries by their IDs |
|
Return one viewable picture attached to an entry, with its summary |
|
Show an entry, and optionally one of its viewable pictures enlarged, in the ARIEL web panel |
|
Copy one viewable picture into the artifact gallery and select it there |
|
Create a new logbook entry |
Search and browse results carry the first ariel.entry_text.listing_chars
characters of each entry’s raw_text, and entries_by_ids the first
ariel.entry_text.read_chars. An entry cut there also carries
raw_text_truncated: true and its full raw_text_length. entry_get
returns the whole entry. See ariel.entry_text: — how much of each entry the agent reads.
Entries carry facility_references, one {start, end, target, kinds, label,
records} per channel address or device id the text quotes. records lists the
records the target names ({kind, id, unit?, description?}, channel before
device); it is empty when the facility file no longer holds the target and
null when no facility file was read. An entry never checked against a facility
file carries no key, and a cut entry lists only the references inside the text
shown. start and end are Unicode code-point offsets into the entry text.
Search and embeddings read the stored text unchanged.
entries_by_ids names each requested ID the logbook does not hold under
missing, mapped to null; when it holds none of them the call fails as
nothing_answered. See Partial Answers.
Attachment summaries#
Every tool that returns entries describes their attachments with one summary
shape, listed under attachments:
{attachment_id?, filename, mime_type, viewable, copy_status, skip_reason?,
caption?, caption_source?, visible_text?, url?}
Listings (search results, browse and entries_by_ids) cut caption
and visible_text to 200 characters and mark a cut field with
caption_truncated or visible_text_truncated; they carry only the first
few summaries and count them all in attachment_count. A search hit that
matched through an attachment names it in matched_attachment_ids.
entry_get returns every summary with its caption in full.
An attachment is viewable when its copy finished (copy_status is
copied), it was not skipped (no skip_reason), its type is an image,
and its display rendition is stored. attachment_view takes the
attachment_id of a viewable attachment and returns a JSON block (the
summary plus entry_id, source_url, size_bytes, rendition_size
and rendition_sha256) followed by the picture. An unknown id is
not_found; an attachment that is not viewable is no_results.
ariel.attachments.view.enabled (default true) switches picture viewing
for the agent. With it off:
attachment_viewandattachment_to_artifactare absent fromtools/list, and a call to either returnsnot_supported;listings carry no
attachments,attachment_countormatched_attachment_ids;entry_getcarries the entry’s storedattachmentsitems unchanged, without summaries.
The web panel’s attachment display does not depend on this setting.
entry_open takes an entry_id and an optional attachment_id and asks
the web terminal to bring the Logbook panel forward at
#sel=<entry_id>, with &att=<attachment_id> when that attachment is
one of the entry’s and is viewable. It returns entry_id,
attachment_id, opened (entry or entry_and_picture), the panel
url and a message; without a web terminal the url is the link to
follow. An unknown entry, or an attachment that is not the entry’s, is
not_found. Followed in a browser, the url opens the web terminal with
ARIEL on that route. The web terminal relays each ARIEL tool call to the
panel’s iframe as osprey-agent-activity {tool, detail, ts}; on
entry_create and entry_publish the list refreshes or counts the new row.
attachment_to_artifact takes the attachment_id of a viewable attachment
and saves its display rendition, never the original upload, to the artifact
gallery as an image artifact in the visualization category, titled with
the filename and entry id. The entry id, attachment id, filename, and caption
with its caption_source are recorded in the artifact’s description and in
metadata.logbook_picture. The artifact is keyed by the rendition’s sha256,
so saving the same picture again returns the same artifact. The result is the
gallery’s usual artifact response (artifact_id, title,
artifact_type, category, gallery_url …) plus entry_id,
attachment_id, created and focused. Errors match
attachment_view’s.
Source: src/osprey/mcp_server/ariel/tools/
Captions and picture search availability#
The presets turn image_caption, image_embedding and
ariel.attachments.view.enabled on. Each picture module runs when its server
and model answer and is skipped otherwise, like semantic search without
Ollama; nothing else stops working. See Picture Captions and Picture Search.
capabilities.attachments carries:
Field |
Meaning |
|---|---|
|
|
|
|
|
|
A deployment without llama-server (or with image_embedding not
reachable for another reason) sees osprey ariel status name the skipped
image_embedding module and why, hybrid_search answer on text only with
the diagnostic “Picture search unavailable — results are matched on text
only, so entries known only by their pictures are missing.”, and
picture_search_unavailable set to the reason.
A deployment without the caption model sees osprey ariel status name
the skipped image_caption module and why; entries are searched on their
text without captions.
Each module is turned off with its own key:
ariel.enhancement_modules.image_caption.enabled: false,
ariel.enhancement_modules.image_embedding.enabled: false, and
ariel.attachments.view.enabled: false for the view tool.
Entry fields#
A facility adapter may declare extra fields an author fills in when an entry
is written (see the Entry Fields section of
Data Ingestion). capabilities lists them under
entry_fields, in form order, and entry_create and entry_publish
take their values as a fields object keyed by field name.
capabilities.entry_fields is a list with one item per declared field:
Field |
Meaning |
|---|---|
|
The key the value is passed under in |
|
How the field is shown and grouped in the entry form |
|
|
|
The form’s pre-filled value; never applied to a value left out |
|
The allowed |
|
Present when declared |
|
Present ( |
|
Present when non-empty: the static fields whose values decide a
|
|
Present ( |
The list is empty when no ingestion adapter is configured or the adapter
declares no fields. When the declarations are broken, entry_fields is
empty and entry_fields_error says what is wrong; the rest of
capabilities still answers.
entry_create checks fields against the declarations before anything is
written. A draft (the default) may leave required fields out; a direct
create may not. Its check covers each value’s type, length, range and
select options, but does not ask the adapter for a dynamic_select’s
current choices. A draft stores the coerced values under fields in the
draft JSON. entry_publish merges its fields over the values stored on
the entry and checks the result in full, including the adapter’s current
dynamic_select choices; a logbook argument wins over a stored or
passed logbook field. Both tools refuse a name that is not declared.
A refused value is a validation_error whose details.field names the
field; for a select the details also carry allowed, the first 50
allowed values. When the adapter cannot list a dynamic_select’s choices,
entry_publish returns internal_error with details.field. Broken
declarations are an internal_error from either tool.
The checks cover shape only. Whether a value is right for the facility is decided by the adapter and the logbook.
Search Result Structure#
Internally, each search produces an ARIELSearchResult with the fields
below; the MCP tools serialize this into their own JSON envelope for the
agent:
Field |
Type |
Description |
|---|---|---|
|
|
Matching entries, ranked by relevance |
|
|
Synthesized answer text (set by callers) |
|
|
Entry IDs used as sources |
|
|
Modes executed (e.g., |
|
|
Explanation of results |
|
|
Structured diagnostics (level, source, message) from search execution |
|
|
Matches across all pages (capped at 1000), whether that count is exact, and whether a later page exists |
Service Factory#
The get_ariel_search_service() function provides a singleton
ARIELSearchService instance. The service is lazily initialized from
config.yml on first access and reused for subsequent calls. The first
access gives the database 10 s to answer; a database that does not answer
raises StoreSilentError and nothing is cached, so the next call asks again.
from osprey.services.ariel_search.capability import (
close_ariel_service,
get_ariel_search_service,
)
async def search_logbook():
service = await get_ariel_search_service()
return await service.search(query="RF cavity fault")
async def shutdown():
await close_ariel_service()
Don’t use the singleton as an async context manager (async with service:):
leaving the block closes the service, and every later call in the process gets
the closed instance. Call close_ariel_service() once, at shutdown.
Lifecycle: The singleton is created once per process. In the web
interface, the create_app() factory manages its own service instance
through the FastAPI lifespan. For cleanup in tests, use
close_ariel_service() (closes the service — its database pools and its
search threads) or reset_ariel_service() (resets without closing).
await service.aclose() is the service’s one close; async with calls it.
It ends every search thread within twice the query-embedding timeout and logs
the name of any still running past it.
Source: src/osprey/services/ariel_search/capability.py
Capabilities API#
The web interface discovers its search modes and tunable parameters dynamically at startup by calling GET /api/capabilities.
The “add a module, get a UI knob for free” pattern: When you register a custom search module with get_parameter_descriptors(), its parameters automatically appear in the web interface’s advanced options panel. The ParameterDescriptor dataclass supports types int, float, bool, text, date, select, and dynamic_select (which fetches options from an API endpoint). Parameters are grouped by section for visual organization.
Security & Resilience
XSS-safe highlights: Search result highlights from PostgreSQL
ts_headlineare sanitized bysanitizeHighlight()incomponents.js— only<b>and</b>tags are preserved; all other HTML is escaped.No cross-origin surface: The interface app registers no CORS middleware. The browser and the
/apiendpoints it calls are served from the same origin, so there is no cross-origin request path to allow or restrict.Frontend fallback: If
/api/capabilitiesis unavailable at startup, the frontend falls back to a default mode list so the interface remains usable.
Technical Reference
All endpoints are mounted under the /api prefix.
Method |
Endpoint |
Description |
|---|---|---|
GET |
|
Discover available search modes and parameters |
GET |
|
Get distinct values for a filterable field ( |
POST |
|
Execute a search query (body: |
GET |
|
List entries newest first: |
GET |
|
Value counts per filter dimension and a day histogram for
|
GET |
|
Get a single entry by ID |
POST |
|
Create a new logbook entry (body: |
POST |
|
Create a new entry from multipart form data with attachments |
GET |
|
Download an attachment binary |
GET |
|
Service health, module status, statistics and |
GET |
|
Read the current ARIEL configuration block |
PUT |
|
Update the ARIEL configuration block |
GET |
|
Describe the configured logbook’s write capability and its declared entry fields (the create form adapts its credential prompt and its field sections to it) |
GET |
|
List the current choices of a declared |
POST |
|
Create a draft entry (pre-fill data for the web form) |
GET |
|
List unexpired drafts, newest first |
GET |
|
Read a draft entry (422 when its file is not a readable draft) |
DELETE |
|
Discard a draft (204); its staged attachments are kept |
GET |
|
Download a draft’s attachment |
GET |
|
|
GET |
|
|
GET |
|
|
Entry fields. GET /api/publish-info returns
{supports_write, requires_auth, source_system, entry_fields}.
entry_fields is always a list, empty when no adapter is configured
or none is declared; its items carry the same keys as the
capabilities.entry_fields items of the MCP server, and a
dynamic_select item also carries options_endpoint
(/entry-fields/{name}/options, relative to the /api prefix).
GET /api/entry-fields/{name}/options returns
{"field": name, "options": [{"value": ..., "label": ...}]}. It reads
only the field’s depends_on values from the query string, each
checked against its own declaration, and is 404 unless name is a
declared dynamic_select. POST /api/entries and
POST /api/entries/upload check the declared values in full,
including the adapter’s current dynamic_select choices, before
anything is written; the adapter receives the declared values only,
and undeclared metadata stays in ARIEL’s copy of the entry. A draft
read from GET /api/drafts/{draft_id} carries the values an agent
stored as fields; POST /api/drafts does not accept them. A
draft id that is not draft-<12 hex> is 422.
Follow-ups. metadata.follows_up names the entry this one
follows up, on POST /api/entries and /upload and in the draft
that entry_publish publishes. It must be an entry ARIEL holds and not the
entry itself; otherwise the refusal names follows_up (REST:
invalid_entry_field; MCP: validation_error). follows_up is
reserved: an adapter cannot declare it. Both create endpoints return
attachments_published: null without attachments, false when
the logbook did not take them and they stayed in ARIEL only.
An entry-field failure on any of these endpoints returns one of three envelopes:
{"detail": "Logbook must be one of: operations, physics", "code": "invalid_entry_field", "field": "book"}
is 422: a submitted value (or an options query’s parent value) is invalid and the author can correct it.
{"detail": "The options for entry field 'scan' are unavailable right now.", "code": "entry_field_options_unavailable", "field": "scan"}
is 502: the adapter failed or took longer than 10 seconds to list a
dynamic_select’s choices. The detail is a generic message, not the
adapter’s error text.
{"detail": "Generic JSON misdeclares entry field 'book': the name is declared more than once", "code": "entry_fields_misdeclared"}
is 500: the adapter declares its fields wrongly, and only a change to the adapter fixes it.
Filters and paging. filters is a JSON object
{"<dimension>": [values], "time": {"start": ..., "end": ...}}: OR
within a dimension, AND across, exact match ignoring case. The
dimensions are author, source_system, tags, each entry field
declared facet: true, and enhancement (enabled enhancement
modules); capabilities.filter_dimensions lists them. On
/api/search the filter is ANDed with the legacy author, source and
date fields. /api/entries pages by an opaque cursor: each page
returns next_cursor, null on the last; page keeps offset paging
and returns no cursor. /api/search pages by offset with
max_results as the page size and returns total, total_exact
and has_more (total_results equals total). A refused
filter or cursor, or page with cursor, is 422
{"detail": {"field": ..., "reason": ...}}. /api/facets counts
over the filter alone when q is blank, else over the mode’s
matches; it returns {available, dimensions, histogram, exact, tier}
and available: false when it cannot count.
Entry shapes. An entry carries subject, entry_url (null for
an entry that exists only in ARIEL, or with no
ariel.entry_url_template) and enhancement_status, where each
enabled module also gets a state of pending, stale,
failed, complete or n/a. view=row returns list rows
instead (RowResponse):
no raw_text, a snippet, the entry’s facets values and its
enhancements states.
GET /health at the root level is the one route the sign-in gate leaves open. It
reports status (healthy or degraded), a fixed message, config_status,
and a service object carrying entry_count, last_ingestion,
enabled_search_modules and enabled_enhancement_modules. service is null
when the panel runs without its search service or the store does not answer. Everything
that names the store (its address, database_uri, the embedding tables and the
driver’s errors) is only on the signed-in /api/status.
HealthResponse:
{
"status": "healthy",
"message": "ARIEL service healthy",
"config_status": "ok",
"service": {
"entry_count": 48291,
"last_ingestion": "2026-09-30T08:00:00Z",
"enabled_search_modules": ["keyword"],
"enabled_enhancement_modules": ["text_embedding"]
}
}
SearchResponse:
Every field is present, at its default when the search left it empty.
search_modes_used names the one mode the search ran; it is empty when the
search timed out or the requested mode is unavailable.
{
"entries": [
{
"entry_id": "12345",
"source_system": "Generic JSON",
"timestamp": "2025-01-15T08:30:00-08:00",
"author": "J. Smith",
"raw_text": "RF cavity trip at 08:15...",
"attachments": [],
"metadata": {},
"created_at": "2025-01-15T08:31:12-08:00",
"updated_at": "2025-01-15T08:31:12-08:00",
"summary": "RF cavity fault requiring manual reset",
"keywords": ["RF", "cavity", "trip"],
"score": 0.92,
"highlights": ["<b>RF cavity</b> trip at 08:15"],
"matched_via": [],
"matched_attachment_ids": [],
"facility_references": null,
"subject": null,
"entry_url": null,
"enhancement_status": {}
}
],
"answer": null,
"sources": ["12345"],
"search_modes_used": ["keyword"],
"reasoning": "Keyword search: 1 results",
"total_results": 1,
"total": 1,
"total_exact": true,
"has_more": false,
"execution_time_ms": 340,
"diagnostics": [],
"expanded_terms": []
}
StatusResponse:
{
"healthy": true,
"database_connected": true,
"database_uri": "postgresql://localhost:5432/ariel",
"entry_count": 15230,
"embedding_tables": [
{"table_name": "text_embeddings_nomic_embed_text", "entry_count": 15230, "dimension": 768, "is_active": true}
],
"active_embedding_model": "nomic-embed-text",
"enabled_search_modules": ["keyword", "semantic"],
"enabled_enhancement_modules": ["text_embedding", "semantic_processor"],
"last_ingestion": "2025-01-15T06:00:00Z",
"errors": [],
"enhancement_coverage": {
"text_embedding": {"label": "Text embedding", "n/a": 0, "not_run": 0, "pending": 120, "stale": 0, "failed": 8, "complete": 15102},
"semantic_processor": {"label": "Summary and keywords", "n/a": 0, "not_run": 0, "pending": 22, "stale": 0, "failed": 8, "complete": 15200}
}
}
enhancement_coverage counts, per enabled module, the entries in each
state; osprey ariel status --json reports it as coverage. A
failed or stale card’s command is
osprey ariel enhance --module <name> --entry <entry_id>, or the
osprey ariel reembed line for a stale text_embedding.
See osprey.interfaces.ariel.api.schemas for the full Pydantic model definitions.
The /api/capabilities endpoint returns a JSON structure that groups enabled search modes under category objects (currently a single direct category), along with shared parameters, the default search mode, the vocabulary state, the attachments block, the filter_dimensions the filter rail offers, and the enabled enhancement_modules. This is the whole response for a deployment with the keyword and semantic modes enabled and no vocabulary or enhancement module; with a vocabulary, expand_query joins the shared parameters:
{
"categories": {
"direct": {
"label": "Direct",
"modes": [
{
"name": "keyword",
"label": "Keyword",
"description": "Fast text-based lookup using full-text search. Use for specific terms, equipment names, PV names, or phrases. Plain words must all appear, with a ranked partial fallback only when no entry has them all; quoted phrases are always required; OR widens, AND/NOT narrow. Dates and authors go in the date and author filters, not the query.",
"parameters": [
{
"name": "include_highlights",
"label": "Include Highlights",
"description": "Include highlighted snippets in search results",
"type": "bool",
"default": true,
"section": "Options"
},
{
"name": "fuzzy_fallback",
"label": "Fuzzy Fallback",
"description": "Fall back to fuzzy matching when no exact matches are found",
"type": "bool",
"default": true,
"section": "Options"
}
]
},
{
"name": "semantic",
"label": "Semantic",
"description": "Find conceptually related entries using text embeddings. Use for queries describing concepts, situations, or events where exact words may not match.",
"parameters": [
{
"name": "similarity_threshold",
"label": "Similarity Threshold",
"description": "Minimum cosine similarity score for results (0-1)",
"type": "float",
"default": 0.5,
"section": "Retrieval",
"min": 0.0,
"max": 1.0,
"step": 0.01
}
]
}
]
}
},
"default_mode": "keyword",
"shared_parameters": [
{
"name": "max_results",
"label": "Max Results",
"description": "Maximum number of entries to return",
"type": "int",
"default": 10,
"section": "General",
"min": 1,
"max": 100,
"step": 1
},
{
"name": "start_date",
"label": "Start Date",
"description": "Filter entries after this date",
"type": "date",
"default": null,
"section": "Filters"
},
{
"name": "end_date",
"label": "End Date",
"description": "Filter entries before this date",
"type": "date",
"default": null,
"section": "Filters"
},
{
"name": "author",
"label": "Author",
"description": "Filter entries by author name",
"type": "text",
"default": null,
"section": "Filters",
"placeholder": "Filter by author..."
},
{
"name": "source_system",
"label": "Source System",
"description": "Filter entries by source system",
"type": "dynamic_select",
"default": null,
"section": "Filters",
"options_endpoint": "/api/filter-options/source_systems"
}
],
"vocabulary": {
"enabled": false,
"concepts": 0,
"expand_by_default": false
},
"attachments": {
"copy_on_ingest": "images",
"formats": {
"viewable": [
"png",
"jpeg",
"gif",
"webp",
"bmp",
"tiff"
],
"reserved": [
"svg",
"pdf",
"text",
"heif",
"video",
"audio",
"archive"
]
},
"view": true,
"captions": false,
"picture_search": false,
"picture_search_unavailable": null
},
"filter_dimensions": [
{
"name": "author",
"label": "Author",
"kind": "builtin"
},
{
"name": "source_system",
"label": "Source System",
"kind": "builtin"
},
{
"name": "tags",
"label": "Tags",
"kind": "builtin"
},
{
"name": "enhancement",
"label": "Enhancements",
"kind": "enhancement"
}
],
"enhancement_modules": []
}
How it works: The get_capabilities() function in osprey.services.ariel_search.capabilities iterates over enabled search modules from the registry. Each module provides a get_tool_descriptor() (for its description) and optionally get_parameter_descriptors() (for its tunable parameters).
App factory: The create_app() function in osprey.interfaces.ariel.app is a standard FastAPI app factory. It accepts an optional config_path argument and returns a fully configured FastAPI application with API routes and static file serving. It registers no CORS middleware — the app and its /api endpoints share one origin, so there is no cross-origin surface.
Lifespan management: The app uses FastAPI’s lifespan context manager to initialize the ARIELSearchService on startup and clean it up on shutdown. During initialization:
Registry bootstrap — pre-creates the framework registry singleton (without an application registry path) so that ARIEL’s search module discovery works even when running outside a full Osprey application.
Config loading — searches for
config.ymlin four locations: the providedconfig_path, theCONFIG_FILEenvironment variable,/app/config.yml(a hand-authored container mount), and the current directory. The DSN is then resolved byresolve_ariel_dsn, which applies theARIEL_DATABASE_HOSTandARIEL_DATABASE_PORToverrides for Docker networking.Service creation — creates the
ARIELSearchServicefrom the loaded config and stores it inapp.state.ariel_service. The database gets 30 s to answer. One that refuses leaves the app in degraded mode; one that does not answer raisesStoreSilentErrorout of the lifespan, so start-up fails withthe ARIEL store at <host>:<port>/<database> did not answer within 30 s.Health check — validates the database connection and logs the result.
Docker environment overrides:
Variable |
Description |
|---|---|
|
Path to config.yml (alternative to default search) |
|
Host the derived DSN dials (e.g., |
|
Port the derived DSN dials (e.g., |
Both overrides apply only where the DSN is derived from services.postgresql. A DSN written out in ariel.database.uri, or in the legacy connection_string, is used verbatim. The ARIEL panel resolves its DSN through the same function, so it does not redirect an authored one either. A blank value counts as unset. A non-integer ARIEL_DATABASE_PORT is refused rather than ignored.
The frontend is a vanilla JavaScript SPA — no build tools, no framework, no transpilation. All files are served as static assets from src/osprey/interfaces/ariel/static/.
JavaScript modules:
Module |
Responsibility |
|---|---|
|
Boot: capabilities, theme, then every pane; the router starts last |
|
One state object, and its two-way mapping to the address hash |
|
Rail and list splitters, stacked mode, drawers, gear menu |
|
The three panes: mailboxes and saved searches, the entry list with search box and mode chip, the entry and picture viewer |
|
The rail’s facet counts and day histogram; Load more |
|
The filter object, and |
|
Saved searches in browser storage; the badge-strip preference |
|
Key bindings; the embedded tile-bar contribution |
|
REST client wrapping |
|
Search driver: runs a (two-phase) search and reports results |
|
Capabilities-driven filters panel (dynamic parameter controls) |
|
The compose sheet and its draft loading and submission |
|
Browser-local compose autosave; the Drafts mailbox |
|
The new entry form’s facility-declared field sections: renders
them from |
|
Status drawer rendering and periodic health refresh |
|
Shared UI components (list rows, banners, loading and error states) |
|
Small shared helpers |
|
Settings UI: read/write ARIEL config block via |
Side-drawer behavior (the Status and Settings drawers) comes
from the shared <osprey-drawer> design-system component rather than
a page-local module.
Theming role: ARIEL is a follower: the web terminal owns the theme pick and broadcasts it, and ARIEL applies what it is sent.
CSS architecture:
File |
Scope |
|---|---|
|
Reset, typography, form elements |
|
Cards, buttons, badges, chips, search results |
|
Header, rail | list | reader panes, stacked mode |
|
Page-level styling around the shared drawer component |
|
Settings drawer styling (config form, YAML editor, save bar) |
Design tokens (colors, spacing, typography, transitions) are not
defined per page — they come from the shared design system’s
/design-system/css/tokens.css.
Routing: The hash is the screen’s state, #q=&mode=&box=&f=&sel=&att=&compose=
(empty keys omitted; box is all, drafts, mine or
saved:<name>; f is the filter as JSON; compose is
draft:<id> for an open draft only), kept in step with history.replaceState. Legacy
aliases are applied and then rewritten canonical: #entry?id=&attachment=
selects the entry and opens the picture, #create[?draft=] opens
the compose sheet, #status opens the Status drawer (embedded: the list), and
#search, #browse or an unknown hash show the list.
Database Schema#
All ingested and enhanced data lives in PostgreSQL. The core enhanced_entries table stores one row per logbook entry with the normalized fields that every adapter produces — entry ID, timestamp, author, raw text, and a JSONB metadata column for facility-specific extras. Enhancement modules write their results either into columns on this same table (keywords, summaries) or into dedicated per-model tables (vector embeddings). The pgvector extension provides the vector column type and cosine-distance operators that power semantic search. Core tables and an embedding table for each configured model are created automatically by osprey ariel migrate, which reads enhancement_modules.text_embedding.models to determine which embedding tables to create. osprey ariel reembed (re)creates and backfills a single model’s table on demand.
pgvector requirement
The pgvector extension is required for semantic search. It is automatically installed in the Osprey-managed PostgreSQL container (osprey up). For external databases, install it manually: CREATE EXTENSION IF NOT EXISTS vector;
Core Tables#
enhanced_entries — Primary storage for logbook entries:
Column |
Type |
Description |
|---|---|---|
|
|
Unique entry identifier |
|
|
Origin system name (e.g., “ALS eLog”) |
|
|
Entry creation time |
|
|
Entry author |
|
|
Full entry text as the source wrote it (subject + details) |
|
|
Subject line derived from the entry ( |
|
|
The channel addresses and device ids the text quotes, as |
|
|
LLM-generated summary (from semantic processor) |
|
|
LLM-extracted keywords (from semantic processor) |
|
|
Additional structured data (title, tags, attachments) |
Per-model embedding tables (e.g., text_embeddings_nomic_embed_text):
Column |
Type |
Description |
|---|---|---|
|
|
Auto-incrementing primary key |
|
|
Foreign key to enhanced_entries |
|
|
pgvector embedding column |
ingestion_runs — Tracks ingestion history:
Column |
Type |
Description |
|---|---|---|
|
|
Auto-incrementing ID |
|
|
Ingestion start time |
|
|
Ingestion completion time |
|
|
Number of new entries added |
|
|
Number of existing entries updated |
|
|
Number of entries that failed |
|
|
Source adapter name |
Migration System#
Migrations are run via osprey ariel migrate and managed by the run_migrations() function in database/migrations.py. When text_embedding is enabled, migrate creates an embedding table for each model listed in enhancement_modules.text_embedding.models (falling back to nomic-embed-text, 768, if none is configured); osprey ariel reembed (re)creates and backfills a single model’s table on demand. migrate also adds the subject column and fills it for existing entries.
Schema Evolution
The current schema was generalised from the logbook formats the shipped ingestion adapters read, and may not capture every field your facility needs. The metadata JSONB column provides flexibility for facility-specific extras, but if your logbook requires a fundamentally different table structure, please open a pull request or contact us — the ingestion and storage layers are designed to accommodate new schemas without disrupting existing ones.