Ports¶

Split text into ordered chunks with char offsets and token counts.

Return the current UTC time.

Cluster the vectors; CPU-heavy work runs in a process pool.

Fetch url; raises on network errors and non-2xx statuses.

Fetch url through the requested adapter route.

Extract body text (and title when derivable) from raw bytes.

Embed document chunks (storage side).

Embed a query (query side; providers may use asymmetric prompts).

Run a cheap canary check that this extractor produces sane output.

Extract mentions with character offsets.

Enqueue a job; returns None when the idempotency key is a duplicate.

Re-enqueue a dead job (resets attempts).

Startup recovery: re-enqueue expired leases and orphaned pending rows.

Returns the number of jobs re-enqueued.

Start the embedded consumer.

Stop the embedded consumer and wait for the in-flight job.

Open connections; idempotent.

Apply pending schema migrations.

Close connections.

Insert a new page row.

Fetch a page by id.

Fetch a page by canonical URL (revisit detection).

Fetch multiple pages preserving input order; missing ids dropped.

Bump last_seen_at and visit_count.

Page ids for one domain, most recently seen first; optionally by status.

Update page lifecycle status.

Fill the body after a deferred fetch resolved it.

metadata, when given, is shallow-merged into the page's existing metadata JSON (e.g. to persist section boundaries alongside the body).

Replace all chunks of a page (canonical chunking).

Hydrate chunks by id; missing ids dropped.

Store the pooled page vector (float32 bytes) for one model.

All page vectors for one model (clustering / similarity).

Remove chunks and page vectors for a page after a core index failure.

Insert a model registry row.

Fetch one registered model.

List registered models, optionally filtered by status.

Return the single active model used by /search.

Update a model's lifecycle status.

Atomically make this the only active model.

Insert a ledger row; False when the idempotency key already exists.

Fetch one job.

List jobs, newest first.

Newest job row for a page payload, optionally restricted by kind.

Indexed pages whose current content has no extract_entities job.

Transition a job to running with a lease.

Transition a job to done.

Record a failed attempt (job stays retryable).

Dead-letter a job after attempts are exhausted.

Reset a dead job to pending with attempts=0 (manual re-enqueue).

Flip running-past-lease jobs back to pending; return them.

All pending ledger rows (startup recovery re-enqueues them).

Return running jobs whose lease expired (read-only; watchdog telemetry).

Job counts grouped by ledger status (absent statuses omitted).

Vector tombstone counts grouped by status (absent statuses omitted).

Insert a watch row; False when (kind, url) already exists.

Fetch one watch.

All watches, newest first.

Full-row update by id; False when the watch does not exist.

Delete a watch; False when it does not exist.

Return enabled watches with next_run_at <= now, most overdue first.

Advance the schedule at enqueue time (decoupled from poll outcome).

Record the outcome of a poll.

Return the first blacklist rule matching this URL/domain, if any.

Atomically: upsert the rule, tombstone + delete matching pages.

Idempotent on pattern (re-forgetting returns the existing rule). Returns the effective rule and the purged page ids. Metadata is authoritative immediately; vectors are deleted asynchronously.

All blacklist rules, newest first.

Remove a rule (does not restore purged content); False if missing.

Tombstones in one status, oldest first.

Advance tombstones.

Remove tombstones (after verified retention expires).

Exact normalized-alias match within a type.

Candidate entities sharing (type, first-token block key).

Insert an entity with its first alias.

Attach an alias (idempotent on (surface_form, entity_id)).

Record mentions (idempotent) and refresh affected entity counts.

Fetch one entity.

Resolve id -> canonical form -> alias (merge-stable references).

All surface forms of an entity.

Pages mentioning an entity.

Entities mentioned on a page.

Blocks holding more than one entity (periodic re-canonicalization).

Merge source into target (snapshot logged first); returns merge id.

Restore a merged entity (LIFO only); returns the restored id.

Recompute idf = ln(N_pages / page_count) for all entities.

Insert or update a cluster row.

Label/keywords are preserved on update when the new values are empty.

Replace a cluster's membership.

Mark clusters tombstoned (rows retained, excluded from listings).

Fetch a cluster (tombstoned included — stale refs degrade gracefully).

Live clusters (optionally tombstoned too), largest first.

Members with soft-membership probability.

Return the live cluster containing this page, if any.

Live cluster per page id; pages without one are absent.

Attach an LLM label.

Record a run start.

Record a run's completion stats.

List cluster runs newest first.

Fetch one cluster run by id.

Persist a run's page and cluster projection coordinates.

Read page and centroid coordinates for a run.

Record lineage events for a run.

Durations of the most recent finished runs.

When the last cluster run finished.

Pages with status=indexed.

Pages indexed after ts.

Most recent last_seen_at across pages (idle detection).

(n_chunks, total_tokens) over the whole corpus — exact estimate.

Page ids (with chunks) ordered by id, after the cursor.

All chunks of one page in ordinal order.

Insert or replace backfill state.

Fetch backfill state.

Persist a completed replay report or terminal error.

Fetch a durable replay result.

Remove a model row and its page vectors (retire).

Fetch and normalize the transcript + chapters into an envelope.

Buffer a query record; never blocks.

Buffer a feedback record; never blocks.

All logged runs, oldest first; optionally bounded below by ts.

Feedback labels per query; the latest label per page wins.

Score all candidates; order of the result is not significant.

Embed normalized surface forms; L2-normalized outputs.

Return normalized transcription; raise on unreadable audio.

Create/update storage so every model has a vector space.

Add a vector space for a newly registered model.

Drop a retired model's vector space.

Idempotently upsert chunks (full point replace, all models).

Add one model's vectors to existing chunks without clobbering others.

Delete all chunks of the given pages across every model space.

Count stored chunks for a page (tombstone verification).

Run dense kNN over one model's vectors.

Sparse/lexical arm; shared across models.

Run both arms and fuse; returns arms + fused + timings.

Release connections/resources.

Return current child items; raises FetchFailedError on I/O failure.