mimir-client 5.0.2

Official Python client for the Mímir Knowledge Graph API

mimir-client

Official Python client for the Mímir Knowledge Graph API.

Installation

pip install mimir-client

Quick Start

import asyncio
from mimir_client import MimirClient

async def main():
    async with MimirClient(api_url="http://localhost:38000", tenant_id=1) 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())

Configuration

Direct instantiation

client = MimirClient(
    api_url="http://localhost:38000",
    tenant_id=1,
    timeout=30.0,
)

From environment variables

from mimir_client import MimirClient, get_settings

# Reads MIMIR_API_URL, MIMIR_TENANT_ID, MIMIR_TIMEOUT from env / .env
settings = get_settings()
client = MimirClient.from_settings(settings)

Environment Variable	Default	Description
MIMIR_API_URL	http://localhost:38000	Mímir API base URL
MIMIR_TENANT_ID	None	Default tenant ID
MIMIR_TIMEOUT	30.0	Request timeout (seconds)

API Coverage

All Mímir v5 REST endpoints are covered:

Resource	Methods
Tenants	create_tenant, get_tenant, get_tenant_by_shortname, list_tenants, update_tenant, delete_tenant, ensure_tenant
Artifact Types	create_artifact_type, get_artifact_type, list_artifact_types, update_artifact_type, ensure_artifact_type
Artifacts	create_artifact, get_artifact, list_artifacts, get_children
Relation Types	create_relation_type, get_relation_type, list_relation_types, update_relation_type, get_inverse_relation_type, ensure_relation_type
Relations	create_relation, get_relation, list_relations, get_artifact_relations
Embedding Types	create_embedding_type, get_embedding_type, list_embedding_types, delete_embedding_type, ensure_embedding_type
Embeddings	create_embedding, get_embedding, list_embeddings
Search	search (unified), search_fulltext
Context	get_context
Provenance	list_provenance_by_artifact, list_provenance_by_source
Health	health, is_healthy

Typed Responses

All methods return Pydantic models with full type information:

artifact = await 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

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

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

HTTP Status	Exception
Connection failure	MimirConnectionError
404	MimirNotFoundError
409	MimirConflictError
422	MimirValidationError
5xx	MimirServerError
Other 4xx	MimirError

Convenience Methods

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

# Safe to call repeatedly — no-op if already exists
tenant = await client.ensure_tenant("dev", "Development")
await client.ensure_artifact_type("document", "Document", category="content")
await client.ensure_relation_type("derived_from", "Derived From", inverse_code="source_of")
await 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/Voyage integration)
• Token budgeting or RAG policies
• Graph traversal algorithms
• Batch operations

Requirements

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

License

MIT