Skip to content

api-reference.md

Latest commit

 

History

History
152 lines (109 loc) · 3.99 KB

api-reference.md

File metadata and controls

152 lines (109 loc) · 3.99 KB
Raw

API Reference

kyvos_sdk.config

KyvosConfig

@dataclass
class KyvosConfig:
    base_url: str = ""
    auth_token: str = ""
    username: str = ""
    password: str = ""
    timeout_seconds: int = 60
    max_retries: int = 5
    retry_backoff_factor: float = 2.0
    mcp_server_url: str = ""
    mcp_pat: str = ""
    mcp_folder_name: str = ""
    mcp_aispace_name: str = ""
    client_mode: str = "rest"

Methods:

  • from_env() -> KyvosConfig — Load from environment variables

kyvos_sdk.client

KyvosService

class KyvosService:
    def __init__(
        self,
        config: KyvosConfig | None = None,
        client: httpx.Client | None = None,
        base_url: str | None = None,
        auth_token: str | None = None,
        username: str | None = None,
        password: str | None = None,
    ) -> None

Lifecycle:

  • initialize() -> None — Login and validate session
  • ensure_authenticated() -> None — Re-login if needed
  • login() -> str — Explicit login, returns session ID
  • logout() -> None — End session

Connection:

  • create_or_update_connection_xml(...) -> tuple[str, bool]
  • create_or_update_connection_json(...) -> tuple[str, bool]
  • create_connection_json(...) -> str

Folders:

  • create_folder(name, folder_type) -> tuple[str, str]
  • list_registered_datasets_in_folder(folder_name) -> dict[str, str]

Datasets:

  • create_dataset(table, connection_name, folder_id, folder_name) -> tuple[str, str]
  • create_dataset_json(table, connection_name, folder_id, folder_name) -> tuple[str, str]
  • refresh_dataset_columns(dataset_id) -> dict
  • get_dataset_column_details(folder_name, dataset_name) -> list[dict]

DRD:

  • create_dataset_relationship_drd(drd_xml) -> None
  • create_dataset_relationship_drd_json(drd_json) -> str
  • resolve_dataset_relationship_id(folder_name, drd_name, ...) -> str
  • get_drd_object_xml(drd_id) -> str
  • parse_drd_structure(drd_xml) -> dict

Semantic Model:

  • create_semantic_model_xml(smodel_xml) -> None
  • create_semantic_model_json(smodel_json) -> None

Dashboard:

  • create_dashboard(dashboard, model_id) -> dict[str, str]

Properties:

  • session_id -> str | None

KyvosServiceError

Raised when a Kyvos API call fails after retries.

kyvos_sdk.auth

KyvosAuthService

class KyvosAuthService:
    def __init__(self, base_url, username, password, ...) -> None

Methods:

  • login() -> str — Authenticate and return session token
  • logout() -> None — End session
  • is_session_valid() -> bool — Check if session is still active
  • get_session_token() -> str | None — Get current token

Exceptions:

  • KyvosAuthError — Base auth error
  • KyvosLoginError — Login failed
  • KyvosLogoutError — Logout failed
  • KyvosSessionExpiredError — Session expired
  • KyvosConnectionError — Cannot connect

kyvos_sdk.protocol

KyvosClient (Protocol)

Abstract interface for Kyvos entity operations. Both KyvosService and future MCPKyvosClient implement this protocol.

kyvos_sdk.factory

get_kyvos_client(config) -> KyvosClient

Returns REST or MCP client based on config.client_mode.

get_kyvos_query_client(config) -> KyvosQueryMCPClient | None

Returns MCP query client if configured, else None.

kyvos_sdk.retry

with_kyvos_retry(fn)

Decorator with exponential backoff for Kyvos API calls.

retry_with_backoff(max_attempts, backoff_factor, retry_on)

Configurable retry decorator.

configure_retry(max_retries, backoff_factor)

Override default retry parameters.

kyvos_sdk.models

Pydantic models: ColumnSpec, TableSpec, DatasetSpec, RelationshipSpec, MeasureSpec, HierarchySpec, SemanticModelSpec, DashboardSpec, DashboardWidgetSpec.

kyvos_sdk.mcp_client

KyvosQueryMCPClient

Query-only client for mcp-kyvos-server v2.2.0.

Methods:

  • execute_query(mdx_query) -> dict
  • get_aispace(aispace_name) -> dict
  • get_semantic_model(model_name) -> dict
  • search_docs(query) -> list[dict]