Skip to content

API Reference

This file is generated from treelang.__all__. Do not edit it by hand; run make docs after changing the supported public API.

AST

Class · treelang.trees.tree

AST()

Represents an Abstract Syntax Tree (AST) for a very simple programming language.

Methods:

  • parse(cls, ast: dict[str, Any] | list[dict[str, Any]]) -> SupportedTree | list[SupportedTree] — Parses the given dictionary or list into a TreeNode.
  • eval(cls, ast: SupportedTree, provider: treelang.ai.provider.ToolProvider, *, limits: treelang.trees.budget.ExecutionLimits | None = None, policy: treelang.trees.policy.ExecutionPolicy | None = None) -> Any — Evaluates the given AST.
  • visit(cls, ast: TraversableNode, op: Callable[[TraversableNode], None] | Callable[[treelang.trees.schemas.v1.TreeNode], None] | Callable[[TreeNodeV2], None]) -> None — Performs a depth-first visit of the AST and applies the given operation to each node.
  • avisit(cls, ast: TraversableNode, op: Callable[[TraversableNode], None] | Callable[[treelang.trees.schemas.v1.TreeNode], None] | Callable[[TreeNodeV2], None] | Callable[[TraversableNode], collections.abc.Awaitable[None]] | Callable[[treelang.trees.schemas.v1.TreeNode], collections.abc.Awaitable[None]] | Callable[[TreeNodeV2], collections.abc.Awaitable[None]]) -> None — Performs an asynchronous depth-first visit of the AST and applies the given operation to each node.
  • repr(cls, ast: SupportedTree) -> str — Returns a string representation of the AST.
  • tool(ast: SupportedTree, provider: treelang.ai.provider.ToolProvider, *, limits: treelang.trees.budget.ExecutionLimits | None = None, policy: treelang.trees.policy.ExecutionPolicy | None = None) -> Callable[..., Any] — Converts the given AST into a callable function that can be added as a tool.

ASTCompilationError

Class · treelang.exceptions

Raised when an AST cannot be compiled into a callable tool.

ASTExecutionError

Class · treelang.exceptions

Raised when an AST fails during execution.

ASTValidationError

Class · treelang.exceptions

Raised when an AST violates a runtime tool contract.

AsyncTreeGrower

Class · treelang.trees.strategies

AsyncTreeGrower(*args, **kwargs)

Asynchronous boundary for model- or evaluation-guided growth.

Methods:

  • grow(self, programs: Sequence[TreeProgram], *, options: GrowthOptions) -> TransformResult[TreeProgram]

AnthropicTransport

Class · treelang.ai.anthropic

AnthropicTransport(*, api_key: str | None = None, timeout: float | None = None, max_tokens: int = 4096, client: Any | None = None, strict_json_schema: bool | None = None) -> None

Translate provider-neutral model requests to Anthropic Messages.

Methods:

  • capabilities(self, model: str) -> ModelCapabilities — Report Claude features, allowing an explicit deployment override.
  • complete(self, request: ModelRequest) -> str
  • consume_usage(self) -> ModelUsage — Return and clear usage for the latest completion in this async context.
  • stream(self, request: ModelRequest) -> AsyncIterator[str]

BranchOutcome

Class · treelang.trees.policy

BranchOutcome(success: bool, value: Any = None, error_type: str | None = None, error_message: str | None = None) -> None

Serializable outcome for one parallel branch in collection mode.

Methods:

  • succeeded(cls, value: Any) -> BranchOutcome
  • failed(cls, error: Exception) -> BranchOutcome

CapabilityAwareTransport

Class · treelang.ai.capabilities

CapabilityAwareTransport(*args, **kwargs)

Optional transport extension for model-specific capability discovery.

Methods:

  • capabilities(self, model: str) -> ModelCapabilities

compose_programs

Function · treelang.trees.composition

compose_programs(programs: Sequence[TreeProgram], *, mode: Literal['single', 'parallel'] = 'single', name: str | None = None, description: str | None = None, limits: TransformationLimits | None = None) -> TransformResult[TreeProgram]

Combine independent programs with hygienic user-function names.

CompiledParameterSource

Typed dictionary · treelang.trees.compilation

Origin metadata for one parameter on a compiled Treelang callable.

Fields:

  • argument_name: str
  • tool_name: str | None
  • function_name: str | None
  • property_schema: dict[str, Any] | None

compiled_parameter_sources

Function · treelang.trees.compilation

compiled_parameter_sources(compiled: Callable[..., Any]) -> dict[str, treelang.trees.compilation.CompiledParameterSource]

Return an isolated parameter-to-origin mapping for a compiled tool.

Raises: ValueError: If compiled was not created by a supporting Treelang compiler.

deduplicate_pure_tool_calls

Function · treelang.trees.deduplication

deduplicate_pure_tool_calls(program: TreeProgram, tools: Sequence[ToolDefinition], *, limits: TransformationLimits | None = None) -> TransformResult[TreeProgram]

Memoize repeated closed calls to declared pure deterministic tools.

ConservativeTreePruner

Class · treelang.trees.pruning

ConservativeTreePruner()

Apply only locally provable rewrites without evaluating external tools.

Methods:

  • prune(self, tree: TreeProgram | TreeNode) -> TransformResult[TreeProgram] | TransformResult[TreeNode] — Return a validated pruned copy, or the original version 1 tree.

CURRENT_SCHEMA_VERSION

Constant · treelang

Current value: '1.0'

DefaultModelCapabilityNegotiator

Class · treelang.ai.capabilities

DefaultModelCapabilityNegotiator() -> None

Conservative capability and structured-output policy.

Stateful in one respect: a provider that rejects the strict schema is not asked again for the same model and schema version. Without that, a rejection costs a wasted round trip on every subsequent request for the life of the negotiator -- the fallback is per-request and nothing has ever written the answer down.

Methods:

  • capabilities(self, transport: object, model: str) -> ModelCapabilities
  • structured_output(self, capabilities: ModelCapabilities, *, model: str, configured_mode: StructuredOutputMode, schema_version: SchemaVersion, tools: list[ToolDefinition]) -> StructuredOutputSelection
  • fallback_after_rejection(self, selection: StructuredOutputSelection, configured_mode: StructuredOutputMode) -> StructuredOutputSelection | None

ExecutionLimitError

Class · treelang.exceptions

ExecutionLimitError(resource: str, limit: int | float) -> None

Raised when an AST invocation exceeds a configured resource limit.

ExecutionLimits

Class · treelang.trees.budget

ExecutionLimits(max_nodes: int | None = None, max_depth: int | None = None, max_call_depth: int | None = None, max_tool_calls: int | None = None, max_concurrency: int | None = None, timeout_seconds: float | None = None) -> None

Optional resource limits for one AST invocation.

None leaves a resource unlimited. Positive values enforce an inclusive maximum, preserving historical behavior when no limits are supplied.

ExecutionPolicy

Class · treelang.trees.policy

ExecutionPolicy(retry: RetryPolicy = <factory>, parallel_failures: Literal['raise', 'collect'] = 'raise') -> None

Opt-in retry and parallel partial-failure behavior.

GrowthOptions

Class · treelang.trees.strategies

GrowthOptions(mode: Literal['single', 'parallel'] = 'single', name: str | None = None, description: str | None = None, limits: TransformationLimits | None = None) -> None

Deterministic options shared by synchronous and asynchronous growers.

MCPToolProvider

Class · treelang.ai.provider

MCPToolProvider(session: mcp.client.session.ClientSession) -> None

Tool provider backed by an initialized MCP client session.

Methods:

  • call_tool(self, name: str, arguments: dict[str, Any]) -> treelang.ai.provider.ToolOutput — Invoke a named tool with validated keyword arguments.
  • list_tools(self) -> list[treelang.ai.tool.ToolDefinition] — Return normalized metadata for every available tool.

ModelAuthenticationError

Class · treelang.exceptions

ModelAuthenticationError(message: str, *, provider: str, status_code: int | None = None, retry_after: float | None = None) -> None

Raised when a model provider rejects authentication or authorization.

ModelCapabilities

Class · treelang.ai.capabilities

ModelCapabilities(strict_json_schema: bool = False, temperature: bool = False) -> None

Features supported by one model through a transport.

ModelCapabilityNegotiator

Class · treelang.ai.capabilities

ModelCapabilityNegotiator(*args, **kwargs)

Policy boundary between model features and request orchestration.

Methods:

  • capabilities(self, transport: object, model: str) -> ModelCapabilities
  • structured_output(self, capabilities: ModelCapabilities, *, model: str, configured_mode: StructuredOutputMode, schema_version: SchemaVersion, tools: list[ToolDefinition]) -> StructuredOutputSelection
  • fallback_after_rejection(self, selection: StructuredOutputSelection, configured_mode: StructuredOutputMode) -> StructuredOutputSelection | None

ModelConnectionError

Class · treelang.exceptions

ModelConnectionError(message: str, *, provider: str, status_code: int | None = None, retry_after: float | None = None) -> None

Raised when the provider SDK cannot reach its model service.

ModelRateLimitError

Class · treelang.exceptions

ModelRateLimitError(message: str, *, provider: str, status_code: int | None = None, retry_after: float | None = None) -> None

Raised when a model provider reports exhausted request capacity.

ModelReplayEntry

Class · treelang.replay

ModelReplayEntry(request: dict[str, Any], response: str | tuple[str, ...], kind: Literal['complete', 'stream'] = 'complete') -> None

One expected model request and completion or stream response.

ModelReplayTransport

Class · treelang.replay

ModelReplayTransport(entries: Sequence[ModelReplayEntry]) -> None

Replay ordered model requests without credentials or network access.

Methods:

  • complete(self, request: ModelRequest) -> str
  • stream(self, request: ModelRequest) -> AsyncIterator[str]
  • assert_consumed(self) -> None — Raise when expected requests remain unconsumed.

ModelTimeoutError

Class · treelang.exceptions

ModelTimeoutError(message: str, *, provider: str, status_code: int | None = None, retry_after: float | None = None) -> None

Raised when the provider SDK times out a model request.

ModelTransport

Class · treelang.ai.transport

ModelTransport(*args, **kwargs)

Minimal model interface required by Arborist orchestration.

Methods:

  • complete(self, request: collections.abc.Mapping[str, Any]) -> str
  • stream(self, request: collections.abc.Mapping[str, Any]) -> collections.abc.AsyncIterator[str]

ModelTransportError

Class · treelang.exceptions

ModelTransportError(message: str, *, provider: str, status_code: int | None = None, retry_after: float | None = None) -> None

Normalized failure returned by a model transport SDK.

ModelUsage

Class · treelang.ai.transport

ModelUsage(prompt_tokens: int = 0, completion_tokens: int = 0) -> None

Token usage reported for one model completion.

NoOpTraceSink

Class · treelang.observability

NoOpTraceSink()

Trace sink that intentionally discards every event.

Methods:

  • record(self, event: str, attributes: collections.abc.Mapping[str, Any]) -> None

Observability

Class · treelang.observability

Observability(logger: logging.Logger = <factory>, tracer: treelang.observability.TraceSink = <factory>, allow_content: bool = False) -> None

Send the same redacted event to JSON logs and an optional trace sink.

Methods:

  • emit(self, event: str, **attributes: Any) -> None

ProviderResponseError

Class · treelang.exceptions

Raised when a provider returns an invalid response.

ProgramCompositionGrower

Class · treelang.trees.strategies

ProgramCompositionGrower()

Default deterministic grower backed by validated program composition.

Methods:

  • grow(self, programs: Sequence[TreeProgram], *, options: GrowthOptions) -> TransformResult[TreeProgram]

ReplayMismatchError

Class · treelang.exceptions

Raised when runtime activity diverges from a deterministic replay.

RetryPolicy

Class · treelang.trees.policy

RetryPolicy(max_attempts: int = 1, delay_seconds: float = 0, idempotent_tools: frozenset[str] = <factory>, retryable_exceptions: tuple[type[Exception], ...] = (<class 'treelang.exceptions.ToolExecutionError'>, <class 'TimeoutError'>)) -> None

Retry transient failures only for tools declared safe to repeat.

StructuredOutputUnsupportedError

Class · treelang.exceptions

Raised when a provider rejects strict structured-output configuration.

StructuredOutputSelection

Class · treelang.ai.capabilities

StructuredOutputSelection(response_format: dict[str, Any], mode: SelectedOutputMode, fallback_reason: str | None = None, negotiated_for: tuple[str, SchemaVersion] | None = None) -> None

Negotiated response format and the reason for compatibility fallback.

SUPPORTED_SCHEMA_VERSIONS

Constant · treelang

Current value: ('1.0', '2.0')

ToolExecutionError

Class · treelang.exceptions

Raised when a provider reports that a tool invocation failed.

ToolDefinition

Typed dictionary · treelang.ai.tool

Provider-neutral metadata for one callable tool.

Fields:

  • name: Required[str]
  • properties: Required[dict[str, treelang.ai.tool.ToolProperty]]
  • description: NotRequired[str | None]
  • input_schema: NotRequired[dict[str, Any]]
  • effects: NotRequired[ToolEffects]

ToolEffects

Typed dictionary · treelang.ai.tool

Optional behavioral guarantees used by safe transformations.

Fields:

  • pure: bool
  • deterministic: bool
  • idempotent: bool

ToolNotFoundError

Class · treelang.exceptions

Raised when a provider does not expose a requested tool.

ToolOutput

Class · treelang.ai.provider

ToolOutput(*, content: Any) -> None

Provider-neutral value returned by one successful tool invocation.

Fields:

  • content: Any

ToolProperty

Typed dictionary · treelang.ai.tool

JSON Schema metadata used for one tool argument.

Fields:

  • type: str | list[str]
  • description: str
  • enum: list[Any]
  • default: Any
  • const: Any
  • minimum: int | float
  • maximum: int | float
  • exclusiveMinimum: int | float
  • exclusiveMaximum: int | float
  • multipleOf: int | float
  • minLength: int
  • maxLength: int
  • pattern: str
  • format: str
  • minItems: int
  • maxItems: int
  • uniqueItems: bool
  • items: Any
  • minProperties: int
  • maxProperties: int
  • properties: dict[str, Any]
  • required: list[str]
  • additionalProperties: bool | dict[str, Any]

ToolProvider

Class · treelang.ai.provider

ToolProvider() -> None

Provider-neutral interface for tool discovery and invocation.

Methods:

  • get_tool_definition(self, name: str) -> treelang.ai.tool.ToolDefinition — Return normalized metadata for one named tool.
  • call_tool(self, name: str, arguments: dict[str, Any]) -> treelang.ai.provider.ToolOutput — Invoke a named tool with validated keyword arguments.
  • list_tools(self) -> list[treelang.ai.tool.ToolDefinition] — Return normalized metadata for every available tool.

ToolReplayEntry

Class · treelang.replay

ToolReplayEntry(name: str, arguments: dict[str, Any], output: Any) -> None

One expected provider invocation and its deterministic output.

ToolReplayProvider

Class · treelang.replay

ToolReplayProvider(tools: Sequence[ToolDefinition], entries: Sequence[ToolReplayEntry]) -> None

Replay an ordered sequence of tool calls and reject any drift.

Methods:

  • list_tools(self) -> list[ToolDefinition] — Return normalized metadata for every available tool.
  • call_tool(self, name: str, arguments: dict[str, Any]) -> ToolOutput — Invoke a named tool with validated keyword arguments.
  • assert_consumed(self) -> None — Raise when expected calls remain unconsumed.

TraceSink

Class · treelang.observability

TraceSink(*args, **kwargs)

Vendor-neutral destination for already-redacted trace events.

Methods:

  • record(self, event: str, attributes: collections.abc.Mapping[str, Any]) -> None

TransformationLimits

Class · treelang.trees.transforms

TransformationLimits(max_nodes: int | None = None, max_depth: int | None = None) -> None

Optional inclusive structural limits for a transformed program.

TransformResult

Class · treelang.trees.transforms

TransformResult(tree: TreeT, lineage: tuple[TransformationRecord, ...] = ()) -> None

A transformed tree together with its complete reproducible lineage.

TransformationRecord

Class · treelang.trees.transforms

TransformationRecord(name: str, changes: tuple[TreeChange, ...] = (), seed: int | None = None) -> None

Named transformation step and the changes it produced.

TreeConditional

Class · treelang.trees.schemas.v1

TreeConditional(*, type: Literal['conditional'] = 'conditional', condition: Node, true_branch: Node, false_branch: Node | None = None) -> None

Represents a conditional statement in the AST.

Fields:

  • type: Literal['conditional']
  • condition: Node
  • true_branch: Node
  • false_branch: Node | None

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeChange

Class · treelang.trees.transforms

TreeChange(kind: TreeChangeKind, path: TreePath, description: str, source_path: TreePath | None = None) -> None

One deterministic structural change made by a transformation.

TreeChangeKind

Class · treelang.trees.transforms

TreeChangeKind(*values)

Structural operations that a transformation can report.

TreeFilter

Class · treelang.trees.schemas.v1

TreeFilter(*, type: Literal['filter'] = 'filter', function: treelang.trees.schemas.v1.TreeLambda, iterable: Node) -> None

Represents a filter operation in the abstract syntax tree (AST).

Fields:

  • type: Literal['filter']
  • function: treelang.trees.schemas.v1.TreeLambda
  • iterable: Node

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeFunction

Class · treelang.trees.schemas.v1

TreeFunction(*, type: Literal['function'] = 'function', name: Annotated[str, MinLen(min_length=1)], params: list[Node]) -> None

Represents a function in the abstract syntax tree (AST).

Fields:

  • type: Literal['function']
  • name: str
  • params: list[Node]

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeLambda

Class · treelang.trees.schemas.v1

TreeLambda(*, type: Literal['lambda'] = 'lambda', params: list[str], body: treelang.trees.schemas.v1.TreeFunction) -> None

Represents an anonymous (lambda) function.

Fields:

  • type: Literal['lambda']
  • params: list[str]
  • body: treelang.trees.schemas.v1.TreeFunction

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeMap

Class · treelang.trees.schemas.v1

TreeMap(*, type: Literal['map'] = 'map', function: treelang.trees.schemas.v1.TreeLambda, iterable: Node) -> None

Represents a map operation in the abstract syntax tree (AST).

Fields:

  • type: Literal['map']
  • function: treelang.trees.schemas.v1.TreeLambda
  • iterable: Node

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeNode

Class · treelang.trees.schemas.v1

TreeNode(*, type: Literal['node'] = 'node') -> None

Represents a node in the abstract syntax tree (AST).

Fields:

  • type: Literal['node']

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any
  • hash(self) -> str

TreePath

Class · treelang.trees.transforms

TreePath(segments: tuple[TreePathSegment, ...] = ()) -> None

Identify a node by field names and zero-based sequence indexes.

Paths are structural rather than object-identity based, so they remain stable across serialization and immutable model copies. The empty path identifies the transformation root.

Methods:

  • child(self, segment: TreePathSegment) -> TreePath — Return a new path extended by one field name or sequence index.

TreeGrower

Class · treelang.trees.strategies

TreeGrower(*args, **kwargs)

Synchronous deterministic program-growth strategy.

Methods:

  • grow(self, programs: Sequence[TreeProgram], *, options: GrowthOptions) -> TransformResult[TreeProgram]

TreePruner

Class · treelang.trees.strategies

TreePruner(*args, **kwargs)

Strategy that returns a tree and reproducible pruning lineage.

Methods:

  • prune(self, tree: GeneratedTree) -> TransformResult[TreeNode] | TransformResult[TreeProgram]

TreeProgram

Class · treelang.trees.schemas.v1

TreeProgram(*, type: Literal['program'] = 'program', body: list[Node], mode: Literal['single', 'parallel'], name: str | None = None, description: str | None = None, schema_version: Literal['1.0'] = '1.0') -> None

Represents a program in the abstract syntax tree (AST).

Fields:

  • type: Literal['program']
  • body: list[Node]
  • mode: Literal['single', 'parallel']
  • name: str | None
  • description: str | None
  • schema_version: Literal['1.0']

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeReduce

Class · treelang.trees.schemas.v1

TreeReduce(*, type: Literal['reduce'] = 'reduce', function: treelang.trees.schemas.v1.TreeLambda, iterable: Node) -> None

Represents a reduce operation in the abstract syntax tree (AST).

Fields:

  • type: Literal['reduce']
  • function: treelang.trees.schemas.v1.TreeLambda
  • iterable: Node

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreeValue

Class · treelang.trees.schemas.v1

TreeValue(*, type: Literal['value'] = 'value', name: Annotated[str, MinLen(min_length=1)], value: JsonValue) -> None

Represents a value in the abstract syntax tree (AST).

Fields:

  • type: Literal['value']
  • name: str
  • value: JsonValue

Methods:

  • eval(self, provider: treelang.ai.provider.ToolProvider, context: ExecutionContext | None = None) -> Any

TreelangError

Class · treelang.exceptions

Base class for errors raised by Treelang.

TreeTransformationError

Class · treelang.exceptions

Raised when a requested tree transformation cannot produce a valid tree.

UsageAwareTransport

Class · treelang.ai.transport

UsageAwareTransport(*args, **kwargs)

Optional transport contract for normalized per-context token usage.

Methods:

  • consume_usage(self) -> treelang.ai.transport.ModelUsage

__version__

Constant · treelang

Current value: '1.4.3'

ast_examples

Function · treelang.trees.schemas

ast_examples() -> str

Return examples for the Treelang AST model.

ast_json_schema

Function · treelang.trees.schemas

ast_json_schema() -> str

Return the JSON schema for the Treelang AST model.

graft_expression

Function · treelang.trees.grafting

graft_expression(program: TreeProgram, graft: Expression, *, at: TreePath, limits: TransformationLimits | None = None) -> TransformResult[TreeProgram]

Replace the expression at at with graft and validate the result.

json_schema_text

Function · treelang.schema_artifacts

json_schema_text(version: SupportedSchemaVersion) -> str

Read one canonical schema exactly as distributed in the package.

load_json_schema

Function · treelang.schema_artifacts

load_json_schema(version: SupportedSchemaVersion) -> dict[str, Any]

Load one canonical schema as a JSON-compatible mapping.

prune_tree

Function · treelang.trees.pruning

prune_tree(tree: TreeProgram | TreeNode) -> TransformResult[TreeProgram] | TransformResult[TreeNode]

Prune a version 2 program, preserving version 1 trees unchanged.

wrap_expression

Function · treelang.trees.grafting

wrap_expression(program: TreeProgram, wrapper: Expression, *, at: TreePath, placeholder: str = 'graft', limits: TransformationLimits | None = None) -> TransformResult[TreeProgram]

Replace placeholder variables in wrapper with the expression at at.