Hypothesis Agents¶

trails.agent.planners.hypothesis implements a scientific reasoning cycle for knowledge graph investigation. The planner follows an observe-hypothesize-test-update loop, producing grounded reports with citations to actual KG nodes.

Hypotheses are first-class objects with PROV-O lineage. The planner returns a standard PlanResult so it composes with existing session infrastructure, budget enforcement, and A/B strategy comparison.

See ADR-0037 for the full design rationale.

Quick start¶

from trails.agent.planners.hypothesis import run, Hypothesis, HypothesisResult

result = run(
    "What patterns exist in the citation network?",
    llm=llm_client,
    session=session,
    ctx=ctx,
    max_hypotheses=3,    # test up to 3 hypotheses before giving up
    min_confidence=0.7,  # confidence threshold for "supported"
    max_steps=15,        # hard upper bound on LLM turns
)

print(result.answer)     # grounded report with citations
print(result.strategy)   # "hypothesis"
print(result.stopped)    # "goal_achieved" | "max_steps" | "error"

# Access the detailed hypothesis result from session metadata
hyp_result: HypothesisResult = session.metadata["hypothesis_result"]
for citation in hyp_result.citations:
    print(f"  {citation.node_iri} (relevance: {citation.relevance})")

Phase cycle¶

The agent follows this phase sequence per hypothesis:

1. Observe -- explores the KG via SPARQL to gather context
2. Hypothesize -- proposes a testable statement with a test plan
3. Test -- executes a SPARQL query or capability call
4. Update -- adjusts confidence based on results; marks supported/refuted/inconclusive
5. Report -- generates a grounded report citing KG nodes

If a hypothesis is refuted and max_hypotheses is not exhausted, the cycle restarts from observe.

Key types¶

API¶