Skip to content

SDK Reference

Python client for the Graffold Knowledge Graph API.

Installation

# From the repo
from sdk.graffold_client import GraffoldClient, AsyncGraffoldClient

GraffoldClient (Sync)

client = GraffoldClient(
    base_url="http://localhost:8000",
    token="your-api-token",
    timeout=60.0,
)

AsyncGraffoldClient (Async)

async with AsyncGraffoldClient("http://localhost:8000", token="...") as client:
    result = await client.search("TP53 role in cancer")

Methods

Method Endpoint Description
client.ingest(entities, relationships) POST /v1/ingest Publish entities to KG
client.search(query, mode="smart") POST /v1/search/{mode} Auto-routed search
client.search_global(query) POST /v1/search/global Community map-reduce
client.search_drift(query) POST /v1/search/drift Multi-hop reasoning
client.search_contradictions(query) POST /v1/search/contradictions Evidence conflicts
client.retrieve(query) POST /v1/retrieve Fast graph retrieval
client.resolve(entities) POST /v1/resolve Entity → canonical ID
client.coverage(entities) GET /v1/atlas/entity-coverage Check KG coverage
client.validate_targets(targets) POST /v1/atlas/validate-targets GNN validation
client.evidence_for_claim(s, p, o) GET /v1/atlas/evidence-for-claim Ranked evidence
client.record_decision(...) POST /v1/atlas/record-decision Decision trace
client.similar_decisions(query) GET /v1/atlas/similar-decisions Cross-session learning
client.export_parquet(dir) POST /v1/export/parquet Export to Parquet
client.import_parquet(dir) POST /v1/import/parquet Import from Parquet
client.detect_communities() POST /v1/communities Community detection

Examples

Ingest

client.ingest(
    entities=[
        {"name": "TP53", "type": "GENE"},
        {"name": "MDM2", "type": "PROTEIN"},
    ],
    relationships=[
        {"source": "TP53", "target": "MDM2", "type": "INHIBITS",
         "properties": {"evidence_level": "rct"}},
    ],
    resolve_entities=True,
)

# Smart (auto-routes)
client.search("What kinases are involved in apoptosis?")

# Specific modes
client.search_global("Main themes in oncology research")
client.search_drift("How does PI3K/AKT affect autophagy?", max_hops=5)
client.search_contradictions("Does metformin help or hurt in cancer?")

Entity Resolution

result = client.resolve([
    {"name": "p53"},
    {"name": "breast cancer"},
    {"name": "imatinib"},
])
# resolved: [
#   {canonical_id: "P04637", source: "uniprot"},
#   {canonical_id: "MONDO:0007254", source: "mondo"},
#   {canonical_id: "5291", source: "pubchem"},
# ]

Coverage Check

coverage = client.coverage(["TP53", "BRCA1", "MDM2", "AKT1"])
# {total: 4, found: 3, coverage: 0.75, missing: ["AKT1"]}