Tools¶

The five framework-neutral tools. Handlers take the same JSON the model sends and return tool-safe dictionaries; the schemas are what an adapter registers with its framework.

retold.tools.handlers ¶

Framework-neutral handlers that apply tool schemas, scope checks, and durable lifecycle operations.

ToolHandlers ¶

Execute the five memory tools without taking identity, authorization, or raw scope IDs from tool input.

tool_schemas ¶

tool_schemas(
    principal: Principal,
) -> list[dict[str, object]]

Return this principal's model-visible tools with only currently writable symbolic destinations.

available_write_targets ¶

available_write_targets(
    principal: Principal,
) -> dict[str, Scope]

Resolve the host's symbolic destinations and discard any scope the principal cannot currently write.

memory_search ¶

memory_search(
    principal: Principal,
    payload: Mapping[str, object],
    *,
    context: str | None = None,
    trigger: Literal["tool", "auto"] = "tool",
) -> dict[str, object]

Search readable memory using adapter-provided context that does not appear in the public schema.

memory_get ¶

memory_get(
    principal: Principal, payload: Mapping[str, object]
) -> dict[str, object]

Return known readable records with conflicts, audit events, and both directions of their lineage.

memory_write ¶

memory_write(
    principal: Principal, payload: Mapping[str, object]
) -> dict[str, object]

Validate one public write payload and delegate durable policy decisions to the ingestor.

memory_revise ¶

memory_revise(
    principal: Principal, payload: Mapping[str, object]
) -> dict[str, object]

Apply a direct record lifecycle revision or a checked entity merge.

memory_forget ¶

memory_forget(
    principal: Principal, payload: Mapping[str, object]
) -> dict[str, object]

Tombstone a writable record, remove its lexical row, and hide its live vector after commit.

retold.tools.schemas ¶

JSON Schema contracts and small dependency-free validation for the five agent tools.

tool_schemas ¶

tool_schemas(
    *, write_targets: Sequence[str] | None = None
) -> list[dict[str, object]]

Return detached schemas in stable order, optionally constraining symbolic write targets.

validate_tool_input ¶

validate_tool_input(
    tool_name: str, payload: Mapping[str, object]
) -> dict[str, object]

Validate the supported JSON Schema subset before a handler reads a caller-controlled value.