API Reference

Authentication

All API calls require Bearer authentication with your project API key.

Authorization: Bearer YOUR_PROJECT_API_KEY

API Reference

Browse the full endpoint reference — schemas, request/response examples, and an interactive try-it panel — at /docs/en/api. Every operation gets its own page generated from the live OpenAPI spec.

Raw spec (for Postman, code generators, custom tools)

The live OpenAPI 3.1 JSON + YAML is publicly hosted — no authentication required — and regenerated on every deploy:

https://api.sonz.ai/docs/openapi.json
https://api.sonz.ai/docs/openapi.yaml

curl -sL https://api.sonz.ai/docs/openapi.json -o openapi.json

REST API

Public HTTP endpoints for agent lifecycle, real-time agent interaction, and proactive delivery. Memory, mood, relationship, and context-management internals are handled by the platform.

Agent Lifecycle

Create an agent

POST /api/v1/agents

Create a new agent. Returns the agent with a platform-generated UUID.

Parameters:

• name (string): Agent name (required)
• personality_prompt (string): Custom system prompt (optional)
• big5 (object): Big Five scores: openness, conscientiousness, extraversion, agreeableness, neuroticism (0.0-1.0)
• speech_patterns (string[]): Speech patterns (optional)
• true_interests (string[]): Agent interests (optional)
• project_id (string): Project UUID to assign agent to (optional)
• language (string): ISO language code, e.g. "en" (optional)

Response: { "agent_id": "uuid", "name": "...", ... }

List agents

GET /api/v1/agents

List agents. Filter by project_id query param.

Parameters:

• project_id (string): Filter by project (query param, optional)

Response: Array of agent objects

Get agent

GET /api/v1/agents/{agentId}

Get agent by ID.

Response: Agent object with personality, mood, profile

Chat

Stream chat

POST /api/v1/agents/{agentId}/chat

Chat with agent via SSE streaming. Returns Server-Sent Events.

Parameters:

• messages (CEChatMessage[]): Conversation messages
• user_id (string): User identifier

Response: SSE stream of chat completion chunks

Proactive Notifications

List notifications

GET /api/v1/agents/{agentId}/notifications

List pending proactive messages.

Parameters:

• status (string): Filter by status: pending | consumed (default: pending, query param)
• user_id (string): Filter by user (optional, query param)
• limit (int): Max results (default: 50, max: 500, query param)

Response: List of proactive messages with message_id, agent_id, user_id, check_type, intent, generated_message, status, created_at

Consume notification

POST /api/v1/agents/{agentId}/notifications/{messageId}/consume

Mark a notification as consumed after delivery.

Response: Confirmation

Notification history

GET /api/v1/agents/{agentId}/notifications/history

List all notifications across all statuses.

Response: Full notification history

Agent Lifecycle (Detailed)

CreateAgent

Creates a new agent with personality configuration. Generates personality prompt, speech patterns, and emotional tendencies.

Request:

• user_id (string): Owner user identifier
• agent_name (string): Agent display name
• gender (string): "male", "female", or "non_binary"
• bio (string): Agent biography (optional)
• avatar_url (string): Avatar image URL (optional)
• big5 (CEBig5Scores): Big Five personality scores (0.0-1.0)
• language (string): Primary language
• equipped_outfit (string): Initial outfit ID (optional)
• skills (CESkillLevel[]): Initial skill levels (optional)
• model_tier (int32): LLM model tier (optional)
• project_id (string): Project to assign agent to (optional)
• agent_id (string): Caller-specified ID for deterministic agents (optional)
• personality_prompt (string): Custom system prompt (optional)
• generate_goals (bool): Auto-generate goals after creation (optional)
• provided_goals (string[]): Store these goals directly (optional)
• speech_patterns (string[]): Speech patterns (optional)
• true_interests (string[]): Agent interests (optional)
• true_dislikes (string[]): Agent dislikes (optional)
• user_display_name (string): Owner display name (optional)
• generate_avatar (bool): Auto-generate an AI avatar on creation (default: true, costs 1 credit). Set to false to skip.

Response: agent_id (UUID), status ('completed' or 'in_progress')

GetAgent

Retrieves an agent's current state including personality, mood, and profile.

Request:

• agent_id (string): Agent UUID

Response: Agent ID, name, bio, gender, avatar_url, Big5 scores, owner, created_at

UpdateAgent

Updates agent fields (name, bio, avatar, personality, interests, speech patterns).

Request:

• agent_id (string): Agent UUID
• name (string): New name (optional)
• bio (string): New bio (optional)
• avatar_url (string): New avatar URL (optional)
• big5 (CEBig5Scores): Updated Big5 scores (optional)
• true_interests (string[]): Updated interests (optional)
• true_dislikes (string[]): Updated dislikes (optional)
• speech_patterns (string[]): Updated speech patterns (optional)
• personality_prompt (string): Updated system prompt (optional)

Response: success (bool)

DeleteAgent

Permanently deletes an agent and all associated data (memory, mood, relationships).

Request:

• agent_id (string): Agent UUID

Response: success (bool)

RegenerateAvatar

Generates or regenerates an AI-created avatar for the agent. Uses LLM to create an image prompt from personality data, then generates and uploads the image. Costs 1 credit. Avatars are auto-generated on agent creation unless disabled.

Request:

• agent_id (string): Agent UUID (URL param)
• style (string): Optional style hint (e.g. 'watercolor anime', 'realistic portrait')

Response: success (bool), avatar_url (string), prompt (string), generation_time_ms (int64)

UpdateAgentPersonality

Updates an agent's authored Big5 personality configuration when your product intentionally changes the agent design.

Request:

• agent_id (string): Agent UUID
• big5 (CEBig5Scores): Updated Big Five scores with confidence

Response: success (bool)

Proactive Behaviors

ScheduleWakeup

Schedules the agent to proactively reach out to a user after a delay.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• check_type (string): Type of check: check_in, follow_up, mood_driven
• intent (string): Why the agent wants to reach out
• delay_hours (int32): Hours to delay before wakeup

Response: wakeup_id (string), scheduled_at (Timestamp)

GetPendingWakeups

Retrieves pending wakeup events for an agent.

Request:

• agent_id (string): Agent UUID

Response: List of PendingWakeup (wakeup_id, user_id, check_type, intent, scheduled_at)

Streaming Chat

Primary public conversation RPC. Send the agent, user, application context, and message history; the platform handles context assembly and state updates automatically.

StreamChat

Streams AI responses for an agent interaction while the platform handles internal memory and state updates behind the scenes.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• session_id (string): Unique session ID
• backend_context (BackendContext): Application state context
• messages (CEChatMessage[]): Conversation messages
• continuation_token (string): Resume from previous response (optional)
• request_type (string): "chat", "guide", or "outing"
• capabilities (string[]): Unlocked capabilities (optional)
• language (string): ISO language code (optional)
• interaction_role (string): "owner" or "non_owner"
• skill_levels (map<string, int32>): Skill levels (optional)
• max_turns (int32): Maximum number of assistant turns per request (optional)

Response: Stream of StreamChatEvent (delta | message_boundary | complete | side_effects | error)

StreamChatEvent is a oneof with these event types:

StreamChatDelta (delta)

• content (string): Text chunk from the AI
• message_index (int32): Index in multi-message response
• is_follow_up (bool): Whether this is a follow-up message
• replacement (bool): If true, replaces all previous content

StreamChatComplete (complete)

• full_content (string): Complete response text
• finish_reason (string): "stop", "length", or "content_filter"
• continuation_token (string): Token for continuing the conversation
• message_count (int32): Number of messages in response

StreamChatError (error)

• message (string): Error message
• code (string): Error code

AI Generation

Platform-managed AI content generation for bios, goals, personalities, diary entries, and images.

GenerateBio

Generates or rewrites an agent's biography using AI based on their personality and context.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• current_bio (string): Current bio for rewriting (optional)
• style (string): Style: casual, formal, poetic, etc. (optional)

Response: bio (string), tone (string), confidence (double)

GenerateGoals

Generates personality-driven goals for an agent based on traits, interests, and memories.

Request:

• agent_id (string): Agent UUID
• agent_name (string): Agent display name
• big5 (CEBig5Scores): Big5 scores
• true_interests (string[]): Agent interests
• true_dislikes (string[]): Agent dislikes
• speech_patterns (string[]): Speech patterns
• recent_memories (CERecentMemory[]): Recent memories for context
• current_goals (CEGoalSummary[]): Existing goals to avoid duplication
• max_goals (int32): Maximum goals to generate
• model_config (CEModelConfig): LLM model configuration (optional)
• custom_context (map<string, string>): Application-specific context (optional)

Response: List of CEGeneratedGoal (type, title, description, priority, related_traits), reasoning

GeneratePersonality

Generates speech patterns and interests from a template and Big5 scores.

Request:

• template_id (string): Template identifier
• base_prompt (string): Base personality prompt
• big5 (CEBig5Scores): Big5 scores
• agent_name (string): Agent name
• gender (string): Agent gender

Response: speech_patterns (string[]), true_interests (string[]), used_fallback (bool)

GenerateDiary

Generates a diary entry from conversation messages and/or application events.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• date (string): Date in YYYY-MM-DD format
• agent_name (string): Agent display name
• language (string): Language for generated content
• messages (CEDiaryMessage[]): Conversation messages (role, content, time)
• trigger_type (string): daily_summary, achievement, milestone, breakthrough
• trigger_context (CEDiaryTriggerContext): Event trigger context (optional)
• model (string): LLM model override (optional)
• temperature (double): Temperature override (optional)
• timezone (string): Timezone for date handling (optional)

Response: user_id, date, diary (title, body_lines, tags), generation_time_ms

GenerateImage

Generates an image from a text prompt and stores it in cloud storage.

Request:

• prompt (string): Image generation prompt
• negative_prompt (string): Negative prompt (optional)
• model (string): Model to use (optional)
• provider (string): Provider to use (optional)
• output_bucket (string): GCS bucket for output (optional)
• output_path (string): Output path in bucket (optional)
• cdn_domain (string): CDN domain for public URL (optional)

Response: success, image_id, gcs_uri, public_url, mime_type, generation_time_ms, error

Voice & Media

Voice matching, text-to-speech, voice chat, and reflection capabilities.

VoiceMatch

Matches an agent to an appropriate TTS voice based on personality traits.

Request:

• big5 (CEBig5Scores): Big5 scores for matching
• preferred_gender (string): Preferred voice gender (optional)
• agent_id (string): Agent UUID (auto-lookup Big5 if provided without big5)

Response: voice_id, voice_name, match_score, reasoning

TextToSpeech

Text-to-speech using Google Gemini voices with emotional context awareness.

Request:

• text (string): Text to convert
• voice_name (string): Gemini voice name
• language (string): Language code (optional)
• emotional_context (CEEmotionalContext): Emotional themes and tone (optional)

Response: audio (bytes), content_type, voice_name

VoiceChat

Single-turn voice chat: transcribes audio, generates AI response, returns TTS audio.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• audio (bytes): Raw audio data
• audio_format (string): Audio format (opus, pcm, wav)
• voice_name (string): TTS voice name
• continuation_token (string): Resume from previous turn (optional)
• language (string): Language code (optional)
• application_id (string): Application identifier (optional)

Response: transcript, response (text), audio (bytes), content_type, continuation_token, side_effects_json

ListVoices

Lists available Gemini TTS voices, optionally filtered by gender.

Request:

• gender (string): Filter by gender (optional)

Response: List of CEGeminiVoice (name, gender)

Reflect

Generates an AI reflection on a capability unlock, milestone, or other event.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• reflection_type (string): "capability_unlock", "milestone", etc.
• capability (string): Capability name
• capability_source (string): Source of capability
• context (string): Additional context string (optional)
• new_capabilities_json (bytes): New capabilities JSON (optional)
• session_id (string): Session ID for auto context build (optional)
• interaction_role (string): "owner" or "non_owner" (default: "owner")

Response: success (bool), reflection (string), side_effects_json (bytes)

Streaming Voice Chat

Bidirectional streaming voice chat with server-side VAD (voice activity detection). Client streams audio chunks continuously; server handles speech detection, transcription, AI response, and TTS.

StreamVoiceChat

Bidirectional streaming: client sends init + audio chunks, server returns transcripts and TTS audio. No manual stop button needed.

Request:

• init (VoiceChatInit): First message: session initialization
• audio_chunk (VoiceAudioChunk): Subsequent messages: raw audio data

Response: Stream of events: ready | vad | transcript | response_delta | audio | turn_complete | error

VoiceChatInit

• agent_id (string): Agent UUID
• user_id (string): User identifier
• audio_format (string): "opus", "pcm", "wav" (default: "opus")
• sample_rate (int32): Sample rate in Hz (default: 48000 for opus)
• voice_name (string): TTS voice name
• language (string): Language code (default: "en")
• application_id (string): Application identifier
• continuation_token (string): Resume from previous session (optional)

VoiceAudioChunk

• audio (bytes): Raw audio data (e.g., Opus frame)
• end_of_speech (bool): Optional client-side VAD hint

Server response events:

VoiceStreamReady

• session_id (string): Assigned session ID

VoiceStreamVAD

• speaking (bool): true = speech started, false = speech ended

VoiceStreamTranscript

• text (string): Transcript text
• is_final (bool): true = final transcript for this utterance

VoiceStreamAudio

• audio (bytes): Audio data chunk
• content_type (string): e.g., "audio/opus", "audio/wav"

VoiceStreamTurnComplete

• continuation_token (string): Token for continuing the session
• side_effects_json (bytes): JSON-serialized AgentSideEffects (optional)

VoiceStreamError

• message (string): Error message
• code (string): "vad_error", "stt_error", "llm_error", "tts_error"
• fatal (bool): If true, session should be closed

Analysis & Search

AI-powered conversation analysis, summarization, and grounded search.

AnalyzeConversation

Analyzes a conversation to extract side effects (personality deltas, habits, memories, etc.).

Request:

• agent_id (string): Agent UUID
• agent_name (string): Agent display name
• user_id (string): User identifier
• messages (CEAnalyzeConversationMessage[]): Messages to analyze (role, content)
• is_final (bool): Whether this is the final batch of messages

Response: success, side_effects_json (bytes), summary, latency_ms

SummarizeConversation

Generates a concise summary of a conversation with topic extraction.

Request:

• messages (CESummarizeConversationMessage[]): Messages (role, content, time)
• agent_name (string): Agent name
• user_name (string): User display name
• max_summary_length (int32): Max summary length in characters

Response: summary (string), topics (string[]), message_count (int)

GenerateSearchQuery

Generates an optimized search query from a topic and category for web search.

Request:

• topic (string): Topic to search for
• category (string): Category for context

Response: query (string), context (string)

GroundedSearch

Performs grounded web search with multiple queries and returns summarized results with sources.

Request:

• queries (string[]): Search queries
• context (string): Context for search relevance
• agent_name (string): Agent name for response framing

Response: List of CEGroundedSearchResult (query, summary, sources with title/url/snippet)

Multi-Agent Dialogue

Agent-to-agent conversations for outings, dialogues, and multi-agent scenes.

AgentDialogue

Generates an agent response in a multi-agent dialogue context (e.g., outings between agents).

Request:

• agent_id (string): Agent UUID (the responding agent)
• user_id (string): User identifier
• messages (CEChatMessage[]): Dialogue messages
• request_type (string): "outing", "dialogue", etc.
• scene_guidance (string): Scene-specific prompt guidance
• tool_config_json (bytes): Tool configuration JSON (optional)
• session_id (string): Session ID for auto context build (optional)
• interaction_role (string): "owner" or "non_owner" (default: "owner")

Response: response (string), side_effects_json (bytes)

Application Events

Notify the platform about significant application events. The platform may generate diary entries, update goals, or take other AI actions. Fires OnDiaryGenerated webhook when diary is created.

TriggerEvent

Accepts application events (achievements, milestones, breakthroughs, completions) and triggers AI content generation.

Request:

• agent_id (string): Agent UUID
• user_id (string): User identifier
• event_type (string): "achievement", "milestone", "breakthrough", "level_up"
• event_description (string): Human-readable context for the AI
• metadata (map<string, string>): Additional context (achievement_id, level, etc.)
• language (string): Language for generated content (default: "en")

Response: accepted (bool), event_id (string)

Knowledge Base

Project-scoped knowledge graph. Upload documents or push structured data via the API — the platform extracts entities, builds a graph, and gives agents a knowledge_search tool to query it during conversations.

Documents

Upload document

POST /projects/{projectId}/knowledge/documents

Upload a document (multipart/form-data with 'file' field, max 50 MB). Returns 202 with document_id and triggers async extraction.

Parameters:

• file (multipart): The document file

Response: document_id, file_name, file_size, checksum, status, gcs_path

List documents

GET /projects/{projectId}/knowledge/documents

List documents. Query: limit (default 50, max 200).

Response: documents[], total

Get document

GET /projects/{projectId}/knowledge/documents/{docId}

Get a single document.

Response: KBDocument object

Delete document

DELETE /projects/{projectId}/knowledge/documents/{docId}

Delete a document.

Response: 204 No Content

Facts & Graph

Insert facts

POST /projects/{projectId}/knowledge/facts

Insert entities and relationships into the knowledge graph. Resolves against existing nodes, creates/updates with version history.

Parameters:

• source (string): Source identifier (default: 'api')
• facts[] (array): Entities: entity_type, label, properties
• relationships[] (array): Edges: from_label, to_label, edge_type

Response: processed, created, updated, details[]

List nodes

GET /projects/{projectId}/knowledge/nodes

List knowledge graph nodes. Query: type (filter), limit (default 100, max 500).

Response: nodes[], total

Get node

GET /projects/{projectId}/knowledge/nodes/{nodeId}

Get a node with connected edges. Query: history=true for version history.

Response: node, outgoing[], incoming[], history[]

Delete node

DELETE /projects/{projectId}/knowledge/nodes/{nodeId}

Soft-delete a node (sets is_active=false).

Response: 204 No Content

Node history

GET /projects/{projectId}/knowledge/nodes/{nodeId}/history

Get version history for a node. Query: limit (default 50, max 200).

Response: history[], total

Search

Search knowledge base

GET /projects/{projectId}/knowledge/search

Full-text search with graph traversal. Query: q (required), limit, history, type, filters (JSON).

Parameters:

• q (string): Search query (required)
• limit (int): Max results (default 20, max 100)
• type (string): Comma-separated entity types to filter
• filters (JSON string): Property filter object
• history (bool): Include version history

Response: query, results[] (with related nodes), total

Schemas

Create schema

POST /projects/{projectId}/knowledge/schemas

Create an entity type schema with fields and optional similarity config.

Parameters:

• entity_type (string): Entity type name (required)
• fields[] (array): Field definitions: name, type, required
• description (string): Schema description
• similarity_config (object): match_fields[], threshold

Response: KBEntitySchema object

List schemas

GET /projects/{projectId}/knowledge/schemas

List entity schemas for a project.

Response: schemas[], total

Update schema

PUT /projects/{projectId}/knowledge/schemas/{schemaId}

Update an entity schema.

Parameters:

• entity_type (string): Updated entity type name
• fields[] (array): Updated field definitions

Response: KBEntitySchema object

Delete schema

DELETE /projects/{projectId}/knowledge/schemas/{schemaId}

Delete an entity schema.

Response: 204 No Content

Stats

Get KB stats

GET /projects/{projectId}/knowledge/stats

Get knowledge base statistics (document counts, node counts, edge count, extraction tokens).

Response: documents {total, indexed, pending, failed}, nodes {total, active}, edges, extraction_tokens

Analytics

Create analytics rule

POST /projects/{projectId}/knowledge/analytics/rules

Create an analytics rule (recommendation or trend).

Parameters:

• rule_type (string): 'recommendation' or 'trend'
• name (string): Rule name
• config (object): Rule configuration
• enabled (bool): Whether the rule is active

Response: KBAnalyticsRule object

Get recommendations

GET /projects/{projectId}/knowledge/analytics/recommendations

Get recommendations. Query: rule_id, source_id (both required), limit.

Response: recommendations[], total

Get trends

GET /projects/{projectId}/knowledge/analytics/trends

Get trend aggregations. Query: node_id (required).

Response: trends[], total

Record feedback

POST /projects/{projectId}/knowledge/analytics/feedback

Record recommendation feedback (shown/converted).

Parameters:

• source_node_id (string): Source node ID
• target_node_id (string): Target node ID
• rule_id (string): Analytics rule ID
• converted (bool): Whether the user converted
• score_at_time (float): Score when recommendation was shown

Response: status: 'recorded'

User Priming

Pre-load user metadata and content so AI agents already "know" users from their first conversation. Metadata (name, company, title) becomes instant facts; content blocks (text, chat transcripts) are processed asynchronously via LLM extraction.

Prime a User

Prime user

POST /agents/{agentId}/users/{userId}/prime

Prime a user with metadata and content. Returns 202 with a job ID; LLM extraction of content runs asynchronously.

Parameters:

• display_name (string): User's display name
• metadata (object): company, title, email, phone, custom (map)
• content[] (array): Content blocks: type ('text', 'chat_transcript'), body
• source (string): Source identifier (e.g., 'crm', 'linkedin')

Response: job_id, status ('queued'), facts_created

Get priming status

GET /agents/{agentId}/users/{userId}/prime/{jobId}

Get the status of a priming job.

Response: ImportJob object (job_id, status, facts_created, error_message, etc.)

Content

Add content

POST /agents/{agentId}/users/{userId}/content

Add content blocks for async LLM extraction (e.g., append chat transcripts after priming).

Parameters:

• content[] (array): Content blocks: type, body
• source (string): Source identifier

Response: job_id, status ('queued')

Metadata

Get user metadata

GET /agents/{agentId}/users/{userId}/metadata

Get priming metadata for a user.

Response: UserPrimingMetadata object

Update user metadata

PATCH /agents/{agentId}/users/{userId}/metadata

Partially update priming metadata. New facts are auto-generated from updated fields.

Parameters:

• display_name (string): Updated name
• company (string): Updated company
• title (string): Updated title
• email (string): Updated email
• phone (string): Updated phone
• custom (map): Custom key-value pairs (merged)

Response: metadata (updated), facts_created

Batch Import

Batch import users

POST /agents/{agentId}/users/import

Import multiple users with metadata and content in a single request. Metadata facts are created synchronously; content extraction runs async.

Parameters:

• users[] (array): Array of {user_id, display_name, metadata, content[]}
• source (string): Source identifier

Response: job_id, status ('queued'), total_users, facts_created

Get import status

GET /agents/{agentId}/users/import/{jobId}

Get the status of a batch import job.

Response: ImportJob object

List import jobs

GET /agents/{agentId}/users/imports

List recent import jobs for an agent. Query: limit (default 20).

Response: jobs[], count

Shared Types

BackendContext

• custom_fields (map<string, string>): Arbitrary application-specific key-value pairs passed through to prompts
• state_json (bytes): Optional structured state as JSON (pass-through to prompts)

CEBig5Scores

• openness (double): Openness to experience (0.0-1.0)
• conscientiousness (double): Organization and discipline (0.0-1.0)
• extraversion (double): Social energy and enthusiasm (0.0-1.0)
• agreeableness (double): Warmth and cooperation (0.0-1.0)
• neuroticism (double): Emotional sensitivity (0.0-1.0)
• confidence (double): Assessment confidence (0.0-1.0)

BFASFacets

Derived from Big5 scores. Read-only in personality profile responses.

• intellect (double): Openness facet — intellectual curiosity (0.0-1.0)
• aesthetic (double): Openness facet — aesthetic sensitivity (0.0-1.0)
• industriousness (double): Conscientiousness facet — self-discipline (0.0-1.0)
• orderliness (double): Conscientiousness facet — preference for order (0.0-1.0)
• enthusiasm (double): Extraversion facet — positive emotion (0.0-1.0)
• assertiveness (double): Extraversion facet — social dominance (0.0-1.0)
• compassion (double): Agreeableness facet — empathy (0.0-1.0)
• politeness (double): Agreeableness facet — deference to others (0.0-1.0)
• withdrawal (double): Neuroticism facet — tendency to withdraw (0.0-1.0)
• volatility (double): Neuroticism facet — emotional instability (0.0-1.0)

BehavioralTraits

Derived from personality. Read-only in personality profile responses.

• response_length (string): How verbose or concise the agent tends to be
• question_frequency (string): How often the agent asks follow-up questions
• empathy_style (string): Approach to emotional support (validating, solution-oriented, etc.)
• conflict_approach (string): How the agent handles disagreements (accommodating, direct, mediating, etc.)

MoodState

• valence (double): Pleasure/displeasure spectrum (0-100)
• arousal (double): Activation/energy level (0-100)
• tension (double): Stress/calmness state (0-100)
• affiliation (double): Social warmth/closeness (0-100)

CEChatMessage

• role (string): "user" or "assistant"
• content (string): Message text
• timestamp (Timestamp): When the message was sent

MemoryCandidate

• content (string): Memory content text
• fact_type (string): preference, commitment, fact, experience, correction
• importance (double): Importance score (0.0-1.0)
• entities (string[]): Related entities

Habit

• name (string): Habit name
• category (string): Habit category
• strength (double): Current strength (0.0-1.0)
• last_observed (Timestamp): Last observation time
• is_formed (bool): Whether the habit is fully formed

CEGoal

• id (string): Goal identifier
• description (string): Goal description
• status (string): "active", "completed", "abandoned"
• priority (string): Priority level
• related_traits (string[]): Related personality traits
• created_at (Timestamp): When the goal was created

Interest

• topic (string): Interest topic
• category (string): Interest category
• confidence (double): Detection confidence (0.0-1.0)
• discovered_at (Timestamp): When the interest was discovered
• research_status (string): "pending" or "researched"

CEModelConfig

• provider (string): LLM provider name
• model (string): Model identifier
• temperature (double): Sampling temperature
• max_tokens (int32): Maximum tokens to generate

ProactiveMessage

• message_id (string): Unique message identifier
• agent_id (string): Agent that generated the message
• user_id (string): Target user
• wakeup_id (string): Associated wakeup event
• check_type (string): Type of check (check_in, follow_up, mood_driven)
• intent (string): Why the agent wants to reach out
• generated_message (string): The actual message text
• status (string): pending, consumed, expired, failed_generation
• created_at (Timestamp): When generated