Skip to main content

Python SDK

Official Python SDK for SemanticFed — async-first, fully typed, built on httpx.

Install​

pip install semanticfed-sdk

# Development install
git clone https://github.com/algoshred/semanticfed-sdk-python.git
cd semanticfed-sdk-python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quick start​

import asyncio
from semanticfed_sdk import SemanticfedSDK


async def main():
    # Defaults to production gateways
    sdk = SemanticfedSDK()

    # Sign in with email/password
    await sdk.auth.sign_in(email="[email protected]", password="secret")

    # SemanticFed-domain operations
    connectors = await sdk.semanticfed.connectors.list()
    metrics = await sdk.semanticfed.metrics.list()

    # Shared cross-product modules
    tags = await sdk.tags.list()

    await sdk.close()


asyncio.run(main())

Environment selection​

The SDK defaults to production. For local or alpha, pass endpoints explicitly:

# Local
sdk = SemanticfedSDK(
    workspace_endpoint="http://127.0.0.1:4003/workspaces/graphql",
    global_endpoint="http://127.0.0.1:4000/global/graphql",
)

# Alpha
sdk = SemanticfedSDK(
    workspace_endpoint="https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://alphagraphql.burdenoff.com/global/graphql",
)

Nested namespaces​

await sdk.semanticfed.connectors.list()
await sdk.semanticfed.data_sources.list()
await sdk.semanticfed.connections.list()
await sdk.semanticfed.models.list()
await sdk.semanticfed.entities.list()
await sdk.semanticfed.dimensions.list()
await sdk.semanticfed.metrics.list()
await sdk.semanticfed.relationships.list()
await sdk.semanticfed.queries.list()
await sdk.semanticfed.query_runs.list()
await sdk.semanticfed.access_policies.list()
await sdk.semanticfed.health.check()

Configuration​

from semanticfed_sdk import SemanticfedSDK

sdk = SemanticfedSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_semanticfed",   # default
    oidc_issuer=None,
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,
    timeout=30.0,
    auto_refresh=True,
)

Error handling​

from semanticfed_sdk import (
    SemanticfedError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
)

try:
    await sdk.auth.sign_in(email="[email protected]", password="wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except SemanticfedError as e:
    print(f"SDK error: {e}")

Development​

make format        # black + isort
make lint          # flake8
make type-check    # mypy (strict)
make test          # pytest
make sanity        # format-check + lint + type-check + test (cov>=80) + build

License​

Proprietary — Copyright Burdenoff Consultancy Services Pvt. Ltd.