mimir-client

Official Python client for the Mimir Knowledge Graph API.

Installation

pip install mimir-client

Quick Start

Synchronous (recommended for scripts, CLI tools, and sync frameworks)

from mimir_client import MimirSyncClient

with MimirSyncClient(api_url="http://localhost:38000", tenant="rademo1") as client:
    # Health check
    healthy = client.is_healthy()
    print(f"API healthy: {healthy}")

    # Create an artifact
    artifact = client.create_artifact(
        "document",
        title="Architecture Overview",
        content="This document describes the system architecture.",
        metadata={"author": "team-lead"},
    )
    print(f"Created: {artifact.id} -- {artifact.title}")

    # Search
    results = client.search(query="architecture")
    for r in results.results:
        print(f"  [{r.score:.2f}] {r.artifact.title}")

Async (for asyncio applications)

import asyncio
from mimir_client import MimirClient

async def main():
    async with MimirClient(api_url="http://localhost:38000", tenant="rademo1") as client:
        # Health check
        healthy = await client.is_healthy()
        print(f"API healthy: {healthy}")

        # Create an artifact
        artifact = await client.create_artifact(
            "document",
            title="Architecture Overview",
            content="This document describes the system architecture.",
            metadata={"author": "team-lead"},
        )
        print(f"Created: {artifact.id} -- {artifact.title}")

        # Search
        results = await client.search(query="architecture")
        for r in results.results:
            print(f"  [{r.score:.2f}] {r.artifact.title}")

asyncio.run(main())

Both clients have identical API surfaces. MimirSyncClient uses httpx.Client (blocking); MimirClient uses httpx.AsyncClient.

Configuration

Direct instantiation

# Tenant identified by shortname (domain identifier)
client = MimirSyncClient(
    api_url="http://localhost:38000",
    tenant="rademo1",
    timeout=30.0,
)

The tenant parameter accepts the tenant shortname string. The client resolves the shortname to the backend integer ID lazily on the first tenant-scoped request. No manual ID lookup is needed.

From environment variables

from mimir_client import MimirSyncClient, MimirClient, get_settings

# Reads MIMIR_API_URL, MIMIR_TENANT, MIMIR_TIMEOUT from env / .env
settings = get_settings()

client = MimirSyncClient.from_settings(settings)  # sync
client = MimirClient.from_settings(settings)       # async

Multi-tenant agents

For agents operating across multiple knowledge graphs, use one client per tenant:

org = MimirSyncClient(api_url="http://mimir:38000", tenant="rademo1-org")
practices = MimirSyncClient(api_url="http://mimir:38000", tenant="rademo1-practices")
project = MimirSyncClient(api_url="http://mimir:38000", tenant="rademo1-project-alpha")

# Each client resolves its own tenant independently
org_results = org.search(query="authentication patterns")
best_practices = practices.search(query="authentication best practices")
project_goals = project.search(query="security requirements")

Backward compatibility

The tenant_id: int parameter is deprecated and will be removed in v6.0.0:

# Deprecated -- emits DeprecationWarning
client = MimirSyncClient(api_url="http://localhost:38000", tenant_id=1)

Providing both tenant and tenant_id raises ValueError.

API Coverage

All Mimir v5 REST endpoints are covered:

Typed Responses

All methods return Pydantic models with full type information:

artifact = client.create_artifact("document", title="Test")
print(artifact.id)          # UUID
print(artifact.title)       # str | None
print(artifact.created_at)  # datetime

Error Handling

Errors are mapped to typed exceptions:

from mimir_client import MimirNotFoundError, MimirConflictError, MimirTenantError

try:
    artifact = client.get_artifact("nonexistent-uuid")
except MimirNotFoundError:
    print("Artifact not found")

try:
    client.create_relation(src_id, tgt_id, "derived_from")
except MimirConflictError:
    print("Relation already exists")

Convenience Methods

ensure_* methods are idempotent -- they return existing resources or create new ones:

tenant = client.ensure_tenant("dev", "Development")
client.ensure_artifact_type("document", "Document", category="content")
client.ensure_relation_type("derived_from", "Derived From", inverse_code="source_of")
client.ensure_embedding_type("nomic", provider="ollama", dimensions=768)

Scope

This client is a thin HTTP wrapper. It does NOT include:

• Embedding generation (use mimir-semantic for Ollama/OpenAI integration)
• Kafka change event consumption (consume mimir.changes.v1 directly)
• Token budgeting or RAG policies
• Graph traversal algorithms
• Batch operations

Mimir change events are delivered through Kafka by the separate mimir.outbox_publisher process. See docs/change-events.md for the event contract and consumer offset requirements.

Requirements

• Python >= 3.11
• httpx
• pydantic >= 2.0
• pydantic-settings >= 2.0

License

MIT