Execute a SurrealQL query and return the results

Ensure a value is a RecordID.

Make HTTP request to the API.

Delete source and clean up associated file, embeddings, and insights.

Save the note and submit embedding command. Overrides ObjectModel.save() to submit an async embed_note command after saving,

Validate URL format for API endpoints. This is a self-hosted application, so we allow: - Private IPs (10.x, 172.16-31.x, 192.168.x) for

Create migration from SQL file.

Detect content type from file extension. Args: file_path: Path to the file (can be full path or just filename) Returns:

Classify a model into a type based on its name and provider. Returns one of: language, embedding, speech_to_text, text_to_speech

Count the number of tokens in the input string using the 'o200k_base' encoding. Args: input_string (str): The input string to count

Split text into chunks using appropriate splitter for content type. Args: text: The text to chunk content_type: Optional exp

Override get() to handle api_key decryption.

Extract command_id from input_data's execution context, or return 'unknown'.

Classify a raw exception into a user-friendly error type and message. Args: exception: Any exception from LLM providers/Esperanto/La

Compare two semantic versions. Args: version1 (str): First version string version2 (str): Second version string Returns

Generate embeddings for multiple texts with automatic batching and retry. Texts are split into batches of EMBEDDING_BATCH_SIZE to avoid exce

Search the knowledge base.

Build CORS headers for error responses. Mirrors Starlette CORSMiddleware behavior: reflects the request Origin when the origin is allowe

Detect content type using content heuristics. Args: text: The text content to analyze Returns: Tuple of (ContentType, c

Generate a single embedding for text, handling large content via chunking and mean pooling. For short text (<= CHUNK_SIZE tokens): -

Get all credentials for a provider.

Returns the best model to use based on the context size and on whether there is a specific model being requested in Config. If context > 105_

Provision environment variables from database for a specific provider. This function checks if the provider has a Credential record stored i

Run the migration.

Build a filesystem-safe output directory path for a podcast episode. Uses a UUID as the directory name so the path is safe regardless of what

Remove thinking content from AI responses, returning only the cleaned content. This is a convenience function for cases where you only need

Get or create the singleton instance and load from DB

Parse message content to extract thinking content from <think> tags. Handles both well-formed tags and malformed output where the opening

Build config dict for AIFactory.create_*() calls. Returns a dict that can be passed as the 'config' parameter to Esperanto's

Load Model record, resolve credential -> (provider, model_name, config_dict). Used by resolve_outline_config, resolve_transcript_config, resolve_

Detect content type using file extension (primary) and heuristics (fallback). Strategy: 1. If file extension is available and recognized

Extract text from LLM response content. Handles both plain string responses and structured content formats (e.g. Gemini's envelope format):

Get a secret from environment, supporting Docker secrets pattern. Checks for VAR_FILE first (Docker secrets), then falls back to VAR. A

Combine multiple embeddings into a single embedding using mean pooling. Algorithm: 1. Normalize each embedding to unit length 2. Com

Build text that exceeds a token threshold.

Check if a provider has any credentials configured in the database.

Convert a ValueError from the service layer to an HTTPException.

Override to encrypt api_key and sync provider extras into `config`.

Get episode profile by name

Get the default embedding model

Get the latest version from the migrations table.

Get a model by ID. Esperanto will cache the actual model instance.

Submit vectorization as a background job using the embed_source command. This method leverages the job-based architecture to prevent

Assert chunks stay within the configured token window.

Check if Azure OpenAI provider is available for a specific mode. Args: mode: One of 'LLM', 'EMBEDDING', 'STT', 'TTS' Returns:

Check if OpenAI-compatible provider is available for a specific mode. Args: mode: One of 'LLM', 'EMBEDDING', 'STT', 'TTS' Retur

Get the first credential for a provider from the database.

Convert a Credential domain object to API response.

Get current database version.

Get the default models configuration from database

Get all models linked to this credential.

Submit a generic command job for background processing

Build context based on provided parameters. Returns: Dict containing the built context with metadata

Decrypt a Fernet-encrypted string value. Handles graceful fallback for legacy unencrypted data. Args: value: The encrypted stri

Build long-form notebook context for podcast and LLM workflows. Normal list retrieval omits large source/note bodies, so this method

Get a specific podcast episode

Get all notes with optional notebook filtering.

Get message count from LangGraph state, returns 0 on error.

Recursively parse and convert RecordIDs into strings.

Raise ValueError if encryption key is not configured.

Add source and its insights to context. Args: source_id: ID of the source inclusion_level: "insights", "full