Reference
Client API
The Python client is split into three surfaces: runtime calls for application traffic, read-only analysis calls for notebooks and reporting, and development/test calls for setup and diagnostics. 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. |
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. |
chunk_vectors(*, dataset: Optional[str] = None) -> dict | Read source chunk vectors. |
hit_stats(query_id: str, *, dataset: Optional[str] = None) -> dict | Read daily hit counts for one query. |
embedding_space(*, dataset: Optional[str] = None) -> dict | Read the dataset's embedding configuration. |
settings(*, dataset: Optional[str] = None) -> dict | Read the retrieval settings in force. |
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 = True) -> dict | Create a Pelorus-managed dataset from a folder (recursive by default; dot-prefixed folders are skipped). It lands disconnected; connect it to a datasource group next. Importing a pre-chunked RAG Connector Dataset is an engine and console operation (PelorusEngine.import_spec_dataset(), or Admin → Datasets → Import), not yet a client call. |
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. |
get_dataset_connect_job(job_id: str) -> dict | Poll a connect job. |
list_active_dataset_connect_jobs() -> list[dict] | List connect jobs still running. |
cancel_dataset_connect_job(job_id: str) -> dict | Cancel a running connect job. |
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. |
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, submitting extraction demand, and reading the
extraction backlog. It is a client API: Pelorus authors every Extract
itself with its configured LLM, and MCP hands out no extraction work.
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(...) |