Return the pool's acquire context manager. Callers must use it as `async with _acquire() as conn:` — NOT `async with await _acquire()`. async

Returns True if the assistant text explicitly declines to answer because the query falls outside the video context. This check prevents

Fetch a YouTube video transcript via Supadata. Args: video_id: YouTube video ID (11 characters) lang: Language code (default

Build the system prompt as a list of content blocks. Returns a multi-block array suitable for ``{"role": "system", "content": [...]}``. When

Force the route's `_client_ip` helper to return a specific IP. ASGITransport's synthetic `request.client.host` is `testclient` — patching at

Return the live pool. Raises if `init_pg_pool` was not called.

Fraction of expected video IDs present in the top-k retrieved video IDs. Duplicates in retrieved list are collapsed before checking.

Reconstruct assistant text from a list of SSE event strings.

Reciprocal Rank Fusion (RRF) to merge ranked results from two retrieval methods. RRF score = Σ 1 / (k + rank_i) across all methods where

Expand each retrieved chunk by its neighbors and merge into contiguous spans. Args: chunks: List of citation-shaped chunk dicts from

Mean of 1/rank for each expected video ID that appears in top-k. Rank is 1-indexed. If none found, 0.

Return an aware UTC datetime. All created_at / updated_at columns are TIMESTAMPTZ in Postgres. asyncpg requires a datetime.datetime for those

Chunk timestamped transcript segments using Docling HybridChunker. Each segment already has precise start/end timestamps from the source

Return the YouTube video description, or None if the lookup fails. Calls YouTube Data API v3 videos.list?part=snippet when YOUTUBE_API_KEY is

Return a sync function that returns MockChannelVideosResult (SDK is sync).

Limit how many chunks from any single video reach the final context. Walks chunks in their input ranking order and drops a chunk once its vid

Create a fresh signed-in client (cookie set) for the given user.

Chunk a video using the existing plain-text chunk_video() function, then add evenly-spaced estimated timestamps. Used when no precise se

Fetch transcript + segments + title for a YouTube URL. Args: url: Full YouTube video URL (watch, shorts, or youtu.be short form).

Return the (video_title, channel_title) from YouTube oEmbed, or (None, None) on failure. Never raises — a missing title falls back to the caller'

Videos with chunk_count where title/description/channel_title contains substring (case-insensitive).

Stream a chat completion via OpenRouter. When tools + executor are supplied, execute tool calls in a loop until finish_reason=stop. All RAG r

Parse a SQLite ISO timestamp string to Postgres TIMESTAMPTZ format.

Post one chat message and return the SSE body. Mocks LLM + DB.

Patch circle.verify_paid_member. fail=True simulates Circle being down (the production verify_paid_member never raises, so we just return False

Embed a list of text strings via OpenRouter in a single batched API call. Args: texts: A list of strings. May be empty (returns [] i

Hybrid retrieval via Reciprocal Rank Fusion (RRF). Args: query_text: Original user query string (used for keyword search) qu

Build a human-readable, tool-aware label for a tool_call_start event. Search tools render the query in quotes; get_video_transcript resolves

Migrate one table: SELECT from SQLite, INSERT into Postgres. Returns the number of rows inserted.

Aggregate metrics for a category.

Create a signed JWT for the given user UUID.

Return a sync function that returns MockTranscriptResult (SDK is sync).

Return conversations owned by user where title contains substring (case-insensitive). Ported from the SQLite era: uses ILIKE in Postgres so the m

Drive `stream_chat` with a canned two-round flow and return emitted chunks. Round 1: model streams a single tool_call. Tool executor:

Drive `stream_chat` end-to-end with a canned two-round flow. Round 1: model streams tool_call args (many chunks, no content). Tool ex

Embed a query, optionally memoizing the result within a turn. The same user turn can issue both ``search_videos`` and ``semantic_search_video

Extract the YouTube video ID from a URL like ``https://www.youtube.com/watch?v=XXXXXXXXXXX``. Returns ``""`` if the URL is empty or doesn

Format chunks as the LLM-facing tool result text. Each chunk is prefixed with a literal ``[c:<chunk_id>]`` marker — the same form the model i

Render chunks as [mm:ss]-annotated transcript. If ``max_chars`` is supplied and the rendered transcript would exceed it, truncate at the last

Convert a body with `## [HH:MM:SS] heading` markers into segments. Each segment is `{start, end, text, heading}`. The end of a segment is the

Full transcript of one video. video_id_whitelist guards against the model hallucinating ids; None disables the check (tests). Defense-in-dept

Dispatch by tool name. Unknown names return an error dict so the model sees the refusal and stops calling. ``embedding_cache`` is optional pe

Extract and validate a YouTube video ID from a URL string. Args: url: A string that may be a YouTube URL. Returns: A Pa

Run a single test case through the retrieval pipeline. Returns a dict with computed metrics and retrieved video IDs.

Concatenate all text blocks into a single string for easy assertions.

Extract a human-readable subject from tool arguments for status events. Returns a short string suitable for display in a "Searching: ..." indicat

Build a Transcript-like object with string content (SDK text mode).

Project a chunk dict onto the canonical citation shape. Different retrieval paths produce slightly different dicts — hybrid retrieval adds an

Parse tool arguments. Returns None on invalid JSON.

Keyword-only (tsvector FTS) search.

Return the set of chunk_ids referenced via ``[c:<id>]`` markers.

Convert an executor result into the `role: tool` message content.

Coerce top_k to a sane integer in [1, maximum].

Apply small-to-big neighbor expansion to already-normalized chunks. Wrapper that imports lazily (expansion.py pulls asyncio.gather over a DB

Split a markdown file into (frontmatter dict, body). Tolerates simple `key: value` and `key: "quoted value"` pairs. Numeric values stay as st

Chunk a video's transcript using Docling HybridChunker. Args: video: A dict with at minimum 'title' and 'transcript' keys. Retu

Close the pool on shutdown. Idempotent.

* Create a mock ReadableStream for SSE response

Hybrid (keyword + semantic via RRF) search.

Semantic-only (pgvector cosine) search.

Create the asyncpg pool if not already created. Idempotent.

Load baseline metrics if present.

Load test cases from the fixture file.