Reference
Client API
The Python client is split into four surfaces: runtime calls for application traffic, read-only analysis calls for notebooks and reporting, development/test calls for setup and diagnostics, and worker calls for external Extract Processing. MCP tools are listed separately because they expose a curated subset for agents.
Connect
| Signature | Use |
|---|---|
PelorusClient.connect(base_url: str, *, api_key: Optional[str] = None, timeout: float = 60.0) -> PelorusClient | Connect to an already-running engine. |
Pelorus.connect(base_url: str, *, api_key: Optional[str] = None, timeout: float = 60.0) -> PelorusClient | Convenience entry point for remote engines. |
Pelorus.local(config: str = "config.yaml", *, host: str = "127.0.0.1", port: Optional[int] = None, startup_timeout: float = 30.0, api_key: Optional[str] = None, timeout: float = 60.0) -> ManagedClient | Start a local engine subprocess and return a client that owns its lifecycle. |
Runtime client
Use these calls in application request paths.
| Signature | Use |
|---|---|
query(query_text: str, *, chunks_only: bool = False, **kwargs) -> QueryResult | Route a query through the selected dataset. Common kwargs include dataset, query_extract, chunks, clusters, and no_cache. |
get_extract(extract_id: str, *, dataset: Optional[str] = None) -> ExtractStatus | Poll the state of an Extract request returned from a query. |
introspect(*, dataset: Optional[str] = None) -> dict | Read analytical state for a dataset without mutating it. |
analysis() -> PelorusAnalysisClient | Open the read-only analysis surface for queries, clusters, projections, vectors, and coverage. |
dev() -> PelorusDevClient | Open the setup, diagnostics, and test surface. |
extract_worker() -> PelorusExtractWorkerClient | Open the external Extract Processing worker surface. |
close() -> None | Close the HTTP connection. |
shutdown() -> None | Close a remote client; for ManagedClient, also shuts down the owned local engine process. |
Analysis client
Use client.analysis() for read-only notebooks, demos, and reports over Pelorus demand state.
Download the runnable notebook: Pelorus Demand Coverage Audit.
| Signature | Use |
|---|---|
snapshot(*, dataset: Optional[str] = None) -> dict | Return the aggregate read model: projections, clusters, coverage, overlaps, memberships, and backlog counts. |
queries(*, dataset: Optional[str] = None, page: int = 1, page_size: int = 50, sort_by: str = "hit_count", sort_order: str = "desc", search: Optional[str] = None) -> dict | List queries for analysis or reporting. |
query(query_id: str, *, dataset: Optional[str] = None) -> Optional[dict] | Read one query detail record. |
query_map(*, dataset: Optional[str] = None, method: str = "umap", refresh: bool = False, clusters_enabled: bool = True, min_cluster_size: Optional[int] = None, min_samples: Optional[int] = None, n_neighbors: Optional[int] = None, min_dist: Optional[float] = None, perplexity: Optional[float] = None, cluster_selection_epsilon: Optional[float] = None, cluster_selection_method: Optional[str] = None) -> dict | Return 2D query-map points and defined cluster centroids. |
chunk_overlay(*, dataset: Optional[str] = None) -> dict | Project source chunks onto the fitted query-map layout. |
project_query(query_text: str, *, dataset: Optional[str] = None) -> dict | Embed and project an ad hoc query into the query-map space. |
vector(item_id: str, *, item_type: str = "query", dataset: Optional[str] = None) -> Optional[dict] | Read a query or cluster vector. |
similarities(item_id: str, *, item_type: str = "query", dataset: Optional[str] = None) -> Optional[dict] | Compute similarities from one query or cluster to other map items. |
similarities_from_vector(vector: list[float], *, dataset: Optional[str] = None) -> dict | Compute similarities from a caller-provided vector. |
embed_query(query_text: str, *, dataset: Optional[str] = None) -> dict | Embed a query with the dataset's embedding configuration. |
cluster_coverage(*, dataset: Optional[str] = None) -> dict | Read cluster coverage and overlap analysis. |
cluster_vectors(*, dataset: Optional[str] = None) -> dict | Read defined cluster centroid vectors. |
query_vectors(*, dataset: Optional[str] = None) -> dict | Read query vectors. |
cluster_membership(*, dataset: Optional[str] = None) -> dict | Read query-to-cluster membership. |
clusters(*, dataset: Optional[str] = None) -> list[dict] | List defined clusters. |
cluster(cluster_id: str, *, dataset: Optional[str] = None) -> Optional[dict] | Read one defined cluster detail record. |
Development and test client
Use client.dev() for setup, diagnostics, and deterministic development workflows.
| Signature | Use |
|---|---|
list_datasets() -> list[dict] | List registered datasets. |
create_managed_dataset(*, name: str, source_folder: Optional[str] = None, overwrite: bool = False, recursive: bool = False) -> dict | Create a Pelorus-managed dataset. It lands disconnected; connect it to a datasource group next. |
get_dataset_connect_plan(dataset: str, group_id: str) -> dict | Preview connecting a dataset to a group. Read-only — no embedding calls. |
connect_dataset_group(dataset: str, group_id: str, vector_policy: str = "reuse_valid") -> dict | Bind a dataset to a group and validate/reuse or re-create its vectors, then rebuild clusters and outlines. vector_policy is "reuse_valid" or "revectorize_all"; use the latter when the embedding configuration changed. |
start_dataset_connect_job(dataset: str, group_id: str, vector_policy: str = "reuse_valid") -> dict | The same, as a background job. Poll with get_dataset_connect_job(job_id); cancel with cancel_dataset_connect_job(job_id). |
register_dataset(folder_path: str) -> dict | Deprecated compatibility path: register a folder in place. |
attach_dataset(folder_path: str) -> DatasetInfo | Attach a dataset folder to the current engine context. |
get_attached_dataset() -> Optional[DatasetInfo] | Return the currently attached dataset, if any. |
add_sources(*, documents: Optional[list[str]] = None, ids: Optional[list[str]] = None, metadatas: Optional[list[dict]] = None, folder_path: Optional[str] = None, dataset: Optional[str] = None) -> dict | Add source text or a folder to a dataset. |
get_dataset_control_status(*, dataset: Optional[str] = None) -> dict | Read enablement and processing status. |
set_dataset_extraction_mode(strategy_id: str, *, dataset: Optional[str] = None) -> dict | Set the dataset extraction strategy. |
enable_dataset(*, dataset: Optional[str] = None) -> dict | Enable a dataset for query traffic. A pure gate — it builds nothing, and requires the dataset to be connected and vector-ready. |
disable_dataset(*, dataset: Optional[str] = None) -> dict | Disable a dataset for query traffic. |
build_document_index(force: bool = False, dump_extracts: bool = False, *, dataset: Optional[str] = None) -> dict | Build or rebuild source document projections. |
refresh_source_indexes(**kwargs) -> dict | Refresh source indexes with management API options. |
get_projection_counts(*, dataset: Optional[str] = None) -> dict | Read vector-store projection counts. |
get_runtime_stats(*, dataset: Optional[str] = None) -> dict | Read runtime retrieval statistics. |
reset_runtime_state(*, dataset: Optional[str] = None) -> None | Reset runtime retrieval state for a dataset. |
submit_extraction_demand(query: str, **kwargs) -> dict | Create an Extract Processing backlog item. |
list_extraction_backlog(**kwargs) -> list[dict] | List backlog items. Common kwargs include dataset, statuses, and limit. |
get_extraction_backlog_item(item_id: str, *, dataset: Optional[str] = None) -> Optional[dict] | Read one backlog item. |
get_extraction_backlog_counts(*, dataset: Optional[str] = None) -> dict | Read backlog counts for a dataset. |
aggregate_extraction_backlog_counts() -> dict | Read server-wide backlog counts. |
start_extraction_batch(**kwargs) -> dict | Start an internal extraction batch. |
get_extraction_batch_run(batch_id: str, *, dataset: Optional[str] = None) -> Optional[dict] | Read an extraction batch run. |
retry_extraction_backlog_item(item_id: str, *, dataset: Optional[str] = None) -> bool | Retry one backlog item. |
cancel_extraction_backlog_item(item_id: str, *, dataset: Optional[str] = None) -> bool | Cancel one backlog item. |
drain_all_extraction_batches(**kwargs) -> list[dict] | Development helper to process queued extraction batches. |
list_extract_processing_runs(**kwargs) -> list[dict] | List Extract Processing runs. |
list_archived_extracts(*, dataset: Optional[str] = None) -> dict | List archived Extract records. |
restore_archived_query(query_id: str, *, dataset: Optional[str] = None) -> bool | Restore an archived query. |
purge_archived_extracts(*, dataset: Optional[str] = None) -> dict | Purge archived Extract records. |
Extract worker client
Use client.extract_worker() when a separate process leases and completes external extraction tasks.
| Signature | Use |
|---|---|
claim_task(*, dataset: Optional[str] = None, lease_seconds: int = 300, max_attempts: int = 3, source_k: int = 5) -> Optional[dict] | Lease the next external extraction task. |
complete_task(task_id: str, lease_id: str, extract: dict, *, dataset: Optional[str] = None, author: Optional[str] = None) -> dict | Complete a leased task with a source-grounded Extract draft. |
fail_task(task_id: str, lease_id: str, *, error: str = "External worker failed task", dataset: Optional[str] = None) -> dict | Mark a task failed, retrying or dead-lettering according to attempt limits. |
nack_task(task_id: str, lease_id: str, *, error: str = "External worker nacked task", dataset: Optional[str] = None) -> dict | Release a task without completing it. |
MCP tool surface
These are the tool names exposed by the MCP facade over the Python client.
MCP scope in this release.
MCP covers retrieval and external extract queue processing. It does
not create or curate clusters; use the Admin UI, management API, or
Python analysis/admin surfaces for cluster work. MCP cluster tools
are a possible later addition.
| Signature | Backed by |
|---|---|
pelorus_query(query_text: str, dataset: Optional[str] = None, no_cache: bool = False, query_extract: Optional[bool] = None, chunks: Optional[bool] = None, clusters: Optional[bool] = None, chunks_only: bool = False) -> dict | client.query(...) |
pelorus_get_extract(extract_id: str, dataset: Optional[str] = None) -> dict | client.get_extract(...) |
pelorus_introspect(dataset: Optional[str] = None) -> dict | client.introspect(...) |
pelorus_submit_extraction_demand(query: str, dataset: Optional[str] = None, reason: str = "mcp", strategy_id: Optional[str] = None, rejected_query_id: Optional[str] = None, rejected_similarity: Optional[float] = None) -> dict | client.dev().submit_extraction_demand(...) |
pelorus_list_extraction_backlog(dataset: Optional[str] = None, status: Optional[str] = None, limit: int = 100) -> list[dict] | client.dev().list_extraction_backlog(...) |
pelorus_get_extraction_backlog_counts(dataset: Optional[str] = None) -> dict | client.dev().get_extraction_backlog_counts(...) |
pelorus_claim_extraction_task(dataset: Optional[str] = None, lease_seconds: int = 300, max_attempts: int = 3, source_k: int = 5) -> Optional[dict] | client.extract_worker().claim_task(...) |
pelorus_complete_extraction_task(task_id: str, lease_id: str, extract: dict, dataset: Optional[str] = None, author: Optional[str] = None) -> dict | client.extract_worker().complete_task(...) |
pelorus_fail_extraction_task(task_id: str, lease_id: str, error: str = "External MCP worker failed task", dataset: Optional[str] = None) -> dict | client.extract_worker().fail_task(...) |
pelorus_nack_extraction_task(task_id: str, lease_id: str, error: str = "External MCP worker nacked task", dataset: Optional[str] = None) -> dict | client.extract_worker().nack_task(...) |
The extract payload
pelorus_complete_extraction_task expects the extract dict in this
shape — it mirrors the Extract anatomy from
How It Works. Completions land as
drafts pending source-grounded validation; they are never served as trusted
answers until promoted.
Excerpts must be verbatim. Copy the text exactly from the
source chunks you were given — do not reword, condense, or resolve a
pronoun inside an excerpt. Excerpts are matched back to their chunks by exact
text, and that match is what establishes the Extract's cited chunk ids. An
excerpt that has been rewritten, however slightly, cannot be matched, and the
Extract is left ungrounded. Put clarifications in
context or in
the summary instead.
{
"context": "Terms, scope, and assumptions needed to interpret the content.",
"content": "The primary strategy-shaped answer payload.",
"excerpts": [
{
"data": "VERBATIM text copied from a source chunk - do not reword.",
"note": "Optional caveat or interpretation detail.",
"source": "optional/source-file.md"
}
]
}The claimed task supplies everything needed to author it: the query, example queries, the top matching source chunks, and a definition of done. If the corpus cannot support an answer, nack the task with a short reason instead of guessing.