Skip to content

AI Answers

Telha does not do "AI-assisted search". It does state-augmented inference: answers generated from planned evidence and verified claim by claim, with an audit trail you can defend months later.

/v1/generate

curl -s -X POST http://127.0.0.1:8080/v1/generate \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{
    "query": "Summarize our current exposure to Meridian Logistics",
    "window": { "atValidTime": "now" },
    "stream": false
  }'

What happens under the hood, in order:

  1. Plan. The memory planner recalls candidate evidence (structured query + semantic search + graph expansion), explodes it to source spans, and packs the best spans under a token budget with per-source diversity caps. Derived summaries are labeled cache and can never support a claim; only truth spans can.
  2. Generate. The LLM (Anthropic or any OpenAI-compatible endpoint, configured operator-side) writes from the planned evidence with [S1]-style citation markers. Prompts are deterministic given the plan.
  3. Verify. The draft decomposes into atomic claims; each claim is scored against the plan's spans (semantic similarity fused with lexical coverage; a claim asserting a number no span states is capped deep into unsupported). Verdicts: supported, partial, unsupported. Policy decides whether unsupported text is flagged or redacted.
  4. Trace. The full record (plan, prompt hash, claims, matches, verdicts, span links) persists. GET /v1/trace/<queryId> returns it; the chat trace viewer renders it clickable down to the source text.

Streaming variant: SSE events chunk (draft text live), then verification (per-claim verdicts, necessarily after the text), then done with the trace id.

Cost governance: per-tenant daily and monthly token caps; exceeding one returns 429 TENANT_BUDGET_EXCEEDED with the reset time. Requests can pass a model from the operator's allowlist only.

Pending clarifications in answers

If an answer depends on a fact that is pending clarification, the response says so explicitly: the evidence chain carries the clarification id, the candidate interpretations, and the reduced confidence. A guessed date is never presented as a confirmed one. Once someone answers the clarification card in Teams or Slack, the correction lands bitemporally and subsequent answers use it with restored confidence.

MCP tools (for agents and assistants)

The MCP server runs inside the core binary (streamable HTTP, default 127.0.0.1:7627; mint a session token with telha api-key mcp-token --tenant --org). Tools:

Tool Does
findRecords Query with expansion (results shaped and truncated for LLM consumption)
getHistory Version history of a record
compareSnapshots Temporal diff between two coordinate pairs
semanticSearch Vector search over a label
createRecord Write a record
getSchema Inferred schema, time-travelable
generate The full plan-generate-verify pipeline
getTrace Claim-grouped trace for any answer

Plus a specs:// resource exposing the design specs themselves, so an agent can read the system's own manuals. Every session binds to one tenant scope at initialize; a token for another tenant mid-session is rejected.

Chat

End users get all of this through the Telha bot (Teams/Slack) and the web chat: streaming answers, tool-call chips showing which tools ran, verification badges per claim, and the trace viewer for click-through provenance. Tool access is role-gated (RBAC allowlists per role) and every invocation lands in the audit log. The same bot delivers clarification questions; the two directions are protocol-separated, so free text can never accidentally become evidence and only explicit card taps record answers.