Context¶

Per-invocation framework context and KG handle.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Symbol	Signature	Description
`Context`	`Context(*, trace_id: str, principal: str, store: Any, session: Any = None, llm: Any = None)`	Per-invocation context passed to capability handlers as `ctx`
`.trace_id`	`str`	Invocation trace id
`.principal`	`str`	Principal string for the caller
`.kg`	`KG`	KG handle bound to the kernel store
`.llm`	`LLMClient`	Lazily-constructed LLM client (from `trails.toml` or override)
`.session`	`Session \\| None`	Optional agent session for cross-invoke state
`.set_llm_override`	`classmethod: set_llm_override(client) -> None`	Install a process-wide override for `ctx.llm` (test seam)
`.clear_llm_override`	`classmethod: clear_llm_override() -> None`	Clear the process-wide `ctx.llm` override

KG¶

ORM-flavoured handle on the kernel graph store. Created by Context, not instantiated directly.

Symbol	Signature	Description
`.add`	`.add(instance) -> None`	Persist a `@node_type` instance (insert-only)
`.save`	`.save(instance) -> bool`	Upsert a `@node_type` instance; returns `True` if existed
`.find`	`.find(model_cls, id_or_iri: str) -> Model \\| None`	Look up a single instance by id or IRI
`.where`	`.where(model_cls, **filters) -> QueryBuilder`	Start a query builder with optional filters
`.query`	`.query(sparql: str, *, reason: bool \\| None = None) -> list[dict]`	Raw SPARQL SELECT/ASK escape hatch
`.update`	`.update(sparql: str) -> tuple[int, int]`	Raw SPARQL UPDATE escape hatch
`.node`	`.node(*, labels: list[str], properties: dict \\| None = None) -> str`	Create a label-first node, return its IRI
`.edge`	`.edge(*, subject: str, label: str, object: str) -> None`	Create a label-first edge triple
`.match`	`.match(*, labels: list[str] \\| None = None, types: list \\| None = None, where: dict \\| None = None) -> list[dict]`	Match nodes by label set and/or `@node_type` with optional filters
`.traverse`	`.traverse(*, subject: str, label: str) -> list[str]`	Walk one edge hop, return neighbor IRIs
`.transaction`	`.transaction() -> Transaction`	Return a write-buffering context manager for atomic writes