Common Library

Domain Model

The persisted model lives in ai.promethist.model. Documents are MongoDB @Document classes; the base contracts Entity, Versionable, WithCreated, WithLastModified and the State enum come from lib.

Organizational Hierarchy

Tenant ──> Project ──> Agent (revisions)

Document Contents

Document	Contents
`Tenant`	Top of the hierarchy, unique by name. Owns billing and pricing.
`Project`	A tenant-scoped configuration container, unique by tenant and name. Holds the consumer-facing branding and terms, the identity providers and whether identity is required, the knowledge specifications, MCP connector and server specifications, navigation, webhook, action and skill specifications, and the recording mode (`Disabled`, `Enabled`, `TestMode`).
`Agent`	The interface implemented by every agent type: `ref`, `name`, `title`, `projectId`, `locales`, `isEnabled`, `hasMemory`, `emotionalSet`, `animationDataType`, `realtimeConfigurationId`, `sttProperties`. Indexed by `(ref, revision)` and `(projectId, state)` — an agent is versioned, so a ref plus a revision identifies an exact definition, and `state` decides who may see it.

Tenant

Top of the hierarchy, unique by name. Owns billing and pricing.

Project

A tenant-scoped configuration container, unique by tenant and name. Holds the consumer-facing branding and terms, the identity providers and whether identity is required, the knowledge specifications, MCP connector and server specifications, navigation, webhook, action and skill specifications, and the recording mode (Disabled, Enabled, TestMode).

Agent

The interface implemented by every agent type: ref, name, title, projectId, locales, isEnabled, hasMemory, emotionalSet, animationDataType, realtimeConfigurationId, sttProperties. Indexed by (ref, revision) and (projectId, state) — an agent is versioned, so a ref plus a revision identifies an exact definition, and state decides who may see it.

Agent Types

Document Purpose

Document	Purpose
`BasicAgent`	Prompt-driven agent: `systemPrompt`, `purpose`, `guardrails`, `identityDescription`.
`RelationalAgent`	Relationship-oriented agent: `identityDescription`, `purpose`, `businessProcessSteps`, `initialPlan`, `guardrails`, `businessImpact`, `sharedMemoryAgentRefs`, plus its own `LLMConfiguration` for initial and relational planning. Its fields, templates and runtime are documented in Relational Management.
`TestAgent`	Agent used to drive automated conversation tests: a required `systemPrompt` and a `noAudio` flag.

BasicAgent

Prompt-driven agent: systemPrompt, purpose, guardrails, identityDescription.

RelationalAgent

Relationship-oriented agent: identityDescription, purpose, businessProcessSteps, initialPlan, guardrails, businessImpact, sharedMemoryAgentRefs, plus its own LLMConfiguration for initial and relational planning. Its fields, templates and runtime are documented in Relational Management.

TestAgent

Agent used to drive automated conversation tests: a required systemPrompt and a noAudio flag.

TemplatableAgent adds templateRef, templateRevision and templateVariables plus apply(), so an agent can be created from a Template (BasicAgentTemplate, RelationalAgentTemplate) whose fields can each be locked. TemplateVariable values are substituted into the agent’s text.

Evaluable is mixed into the agent types that can be evaluated, carrying the evaluation definitions to run.

Conversation

Document Contents

Document	Contents
`Session`	One conversation. Indexed by `(agent.ref, created)`, `(projectRef, created)` and `(userId, agent.ref, created)`. Carries the device, agent snapshot, project and tenant, the user, turn count and last turn, summary, rating, sensory data, arbitrary `attributes`, multimodal statistics, the user/agent/blended emotional sets, the conversation scores, the lifecycle `state` (`OPEN`, `ENDED`, `ABANDONED`, `DISCONNECTED`), the evaluation results state and the refs of the navigation entries the session-end navigation judge unlocked.
`Turn`	One exchange within a session: raw `input` and `output` elements, the final `transcript`, a derived `response` (output without the `#` commands) and a `log` with the turn’s timing.
`Device`	A client device or channel, unique by `ref`. Created on first sight, which is what allows an anonymous user to be recognized on the same device.
`User`	A platform user, unique by `username`, with gender and registered push tokens.

Session

One conversation. Indexed by (agent.ref, created), (projectRef, created) and (userId, agent.ref, created). Carries the device, agent snapshot, project and tenant, the user, turn count and last turn, summary, rating, sensory data, arbitrary attributes, multimodal statistics, the user/agent/blended emotional sets, the conversation scores, the lifecycle state (OPEN, ENDED, ABANDONED, DISCONNECTED), the evaluation results state and the refs of the navigation entries the session-end navigation judge unlocked.

Turn

One exchange within a session: raw input and output elements, the final transcript, a derived response (output without the # commands) and a log with the turn’s timing.

Device

A client device or channel, unique by ref. Created on first sight, which is what allows an anonymous user to be recognized on the same device.

User

A platform user, unique by username, with gender and registered push tokens.

The fields returned to clients — which is a subset of the above — are documented in Session API.

Memory and Knowledge

Document Contents

Document	Contents
`MemoryUnit`	The base contract of a stored memory unit, with an ID derived from a ref and a type.
`ChatMemoryUnit`	The chat message history of a session.
`DataMemoryUnit`	Arbitrary typed data with a revision history, so a value’s evolution is preserved.
`MemoryState`	A snapshot of a user’s whole memory — data, short-term and session memory units — created and restored through the memory endpoints.
`Skill`, `SkillSpecification`	A named agent skill, defined as Markdown-like instruction content.
`KnowledgeSpecification`	A knowledge source of a project — static text, a file or a URL.

MemoryUnit

The base contract of a stored memory unit, with an ID derived from a ref and a type.

ChatMemoryUnit

The chat message history of a session.

DataMemoryUnit

Arbitrary typed data with a revision history, so a value’s evolution is preserved.

MemoryState

A snapshot of a user’s whole memory — data, short-term and session memory units — created and restored through the memory endpoints.

Skill, SkillSpecification

A named agent skill, defined as Markdown-like instruction content.

KnowledgeSpecification

A knowledge source of a project — static text, a file or a URL.

See Memory for how these are read and written.

Evaluation

Document Contents

Document	Contents
`EvaluationDefinition`	One evaluation: its prompt, `executionModes` (`PER_TURN`, `ON_CONVERSATION_END`), lookback window and whether it is user-facing or admin-facing.
`EvaluationGroupDefinition`	Groups insights under an evaluation, with an order.
`EvaluationInsightDefinition`	The schema of a single insight — `Bool`, `Number`, `Text` or `TextList`.
`EvaluationResult`, `EvaluationInsightResult`	Recorded outcomes per session, user and agent, including the agent revision and state at the time, the value, the reasoning and the supporting evidence.
`FeaturedEvaluationDefinition`, `FeaturedEvaluationResult`	The single headline outcome shown to the user.

EvaluationDefinition

One evaluation: its prompt, executionModes (PER_TURN, ON_CONVERSATION_END), lookback window and whether it is user-facing or admin-facing.

EvaluationGroupDefinition

Groups insights under an evaluation, with an order.

EvaluationInsightDefinition

The schema of a single insight — Bool, Number, Text or TextList.

EvaluationResult, EvaluationInsightResult

Recorded outcomes per session, user and agent, including the agent revision and state at the time, the value, the reasoning and the supporting evidence.

FeaturedEvaluationDefinition, FeaturedEvaluationResult

The single headline outcome shown to the user.

The client-facing shape of these results is documented in Evaluation API.

Feedback

Document Contents

Document	Contents
`FeedbackDefinition`	One survey: its trigger point (`AfterSession` or `BeforeSession`), its entries — each with an `order`, a mode (`SingleQuestion` or `Carousel`), an optional session-length branch and its questions — and how it is scheduled (`schedulingMode` with `periodicInterval`, `usageBasedThreshold` or `evaluationCondition`), its `priority`, and its `state` and `revision`. Each revision is a document of its own, with its own `id`, and the revisions share a `ref`.
`FeedbackQuestionDefinition`	A reusable question: `Thumbs`, `StarRating`, `LinearScale`, `MultipleChoice`, `SingleChoice` or `Text`, specific to a project or global. It has its `text` and an optional Markdown `description`.
`Feedback`	One serving of a definition to a user and the reaction to it: the `id` of the definition revision and its `revision`, the session and project, when it was `requested` and `submitted`, and the `answers`, whose `value` is null for a skipped question. Its `state` (`Requested`, `Postponed`, `Skipped` or `Answered`) is derived from these.

FeedbackDefinition

One survey: its trigger point (AfterSession or BeforeSession), its entries — each with an order, a mode (SingleQuestion or Carousel), an optional session-length branch and its questions — and how it is scheduled (schedulingMode with periodicInterval, usageBasedThreshold or evaluationCondition), its priority, and its state and revision. Each revision is a document of its own, with its own id, and the revisions share a ref.

FeedbackQuestionDefinition

A reusable question: Thumbs, StarRating, LinearScale, MultipleChoice, SingleChoice or Text, specific to a project or global. It has its text and an optional Markdown description.

Feedback

One serving of a definition to a user and the reaction to it: the id of the definition revision and its revision, the session and project, when it was requested and submitted, and the answers, whose value is null for a skipped question. Its state (Requested, Postponed, Skipped or Answered) is derived from these.

How the engine schedules and delivers them is described in Feedback Scheduling; the client-facing shape in Feedback API.

Coaching

Built on top of the evaluation results, once a conversation has ended — see Codebook and Development Profile.

Document Contents

Document	Contents
`CodebookCode`	One recurring pattern a project’s evaluations keep describing: a short name and the meaning that distinguishes it from the others. Coined by the model, unique per project and name.
`CodebookOccurrence`	One evaluation output filed under a code, with the subject it came from, its user and session, and the time it was recorded. `codeId` is null while the text is still unclassified, which is what a growth pass claims.
`DevelopmentProfile`	One coaching profile per project and user. Holds the authored content, the digest of the evidence it was generated from, and whether it needs review.

CodebookCode

One recurring pattern a project’s evaluations keep describing: a short name and the meaning that distinguishes it from the others. Coined by the model, unique per project and name.

CodebookOccurrence

One evaluation output filed under a code, with the subject it came from, its user and session, and the time it was recorded. codeId is null while the text is still unclassified, which is what a growth pass claims.

DevelopmentProfile

One coaching profile per project and user. Holds the authored content, the digest of the evidence it was generated from, and whether it needs review.

Access, Billing and Integration

Document Contents

Document	Contents
`AccessControlList`	A role grant scoped to a tenant or project, for an internal user or an external identity (identity provider ref plus role). See Security Model and Security Implementation.
`AuditEvent`	An audit record: entity type and ID, action, actor and actor type.
`BillingDetails`, `PricingDetails`, `Pricing`	The tenant’s billing linkage and its pricing model (per seat, or per seat and minutes).
`Secret`	A tenant- and project-scoped credential, by type.
`OAuthToken`	A user’s token for a third-party service, unique per user and service ref.
`McpConnector`, `McpConnectorSpecification`, `McpServerSpecification`, `McpIntegrationSpecification`	Model Context Protocol integration: the registered connector with its loaded tool specifications, and the project-level configuration describing it.
`IdentityProvider`	An identity provider offered by a project.
`RealtimeConfiguration`	A reusable realtime (speech-to-speech) configuration referenced by agents.
`RealtimeTokenUsage`	Token usage of a realtime session — text and audio, input, output and cached — aggregatable with `+`.
`ActionSpecification`, `ShownMultimodal`, `AgentRefFilter`	Project-defined client actions, the record of a multimodal interaction shown to a user, and the agent ref filter used by evaluation queries.

AccessControlList

A role grant scoped to a tenant or project, for an internal user or an external identity (identity provider ref plus role). See Security Model and Security Implementation.

AuditEvent

An audit record: entity type and ID, action, actor and actor type.

BillingDetails, PricingDetails, Pricing

The tenant’s billing linkage and its pricing model (per seat, or per seat and minutes).

Secret

A tenant- and project-scoped credential, by type.

OAuthToken

A user’s token for a third-party service, unique per user and service ref.

McpConnector, McpConnectorSpecification, McpServerSpecification, McpIntegrationSpecification

Model Context Protocol integration: the registered connector with its loaded tool specifications, and the project-level configuration describing it.

IdentityProvider

An identity provider offered by a project.

RealtimeConfiguration

A reusable realtime (speech-to-speech) configuration referenced by agents.

RealtimeTokenUsage

Token usage of a realtime session — text and audio, input, output and cached — aggregatable with +.

ActionSpecification, ShownMultimodal, AgentRefFilter

Project-defined client actions, the record of a multimodal interaction shown to a user, and the agent ref filter used by evaluation queries.

Logging and Testing

model/logging/ holds the structured records of model invocations — LLMLog, Message, Tool, Usage and RecordedRealtimeEvent. model/testing/RecordedToolEvent records a tool invocation for replay. These are what the session debugger reads.

ToolCallCriteria specifies, per tool name or pattern and project (optionally one agent), when a tool should and should not be called; it is versioned by ref and revision, edited as a draft and used for classification once published. ToolCallClassification stores the verdict for one tool in one turn against one criteria revision — see Tool Call Analysis.