Quick start

This walks through the shortest path: install the SDK, point it at a database, get an answer with an evidence chain.

1. Sign up + create a database

   At owlgraph.ai/signup, create a free Developer account. From the dashboard, click Create database and choose the Reference Pizza preset on the ingest tab — that loads a small typed knowledge graph you can query immediately. (Want to use your own data? Skip the preset and ingest a corpus — that walk-through is in Loading your data.)

2. Mint an API key

   Dashboard → Settings → API Keys → New key. Copy it once — you won’t see it again. The key starts with sk-owl-.

3. Install the SDK

   pip install owlgraph-core

   Requires Python 3.12+. The only runtime dependency outside the standard library is httpx.

4. Ask a question

   from owlgraph_core import sdk as owl
   
   db = owl.connect(
       database_id="<your-database-uuid>",
       api_key="<your-api-key>",   # or set OWLGRAPH_API_KEY
   )
   
   result = db.retrieve("Who invented Hawaiian pizza?")
   print(result.answer)
   
   for p in result.passages:
       print(f"  - {p.source}: {p.text[:200]}")

   You should see the answer plus the supporting passages — every claim traceable back to corpus text.

5. Inspect the evidence chain

   result.trajectory is the inner agent’s reasoning trail — every tool call, every entity resolved, every edge traversed. Useful for debugging, auditing, and replaying in your eval suite.

   for step in result.trajectory:
       print(step.tool, step.arguments, "→", step.result_summary)

   For more detail, pass trace="full":

   result = db.retrieve("question", trace="full")

• SDK reference — every method, every argument, error semantics
• Core concepts — what’s a typed entity, what’s an evidence chain, how does the agent decide what to retrieve
• Loading your data — getting your own corpus into a database

AuthError: no API key — you didn’t pass api_key= and OWLGRAPH_API_KEY isn’t in your environment. Either inject it explicitly or export OWLGRAPH_API_KEY=sk-owl-....

AuthError: authentication failed — the key was rejected. Most often: the key was revoked or it’s scoped to a different database. Mint a new one in the dashboard.

RateLimitError — you’ve exceeded the per-key rate limit. The error carries a retry_after field (seconds). For sustained higher throughput, contact support — limits are per-tenant, not per-key.