as_tool

sdk.as_tool(*, scope="user", user_id=None, customer_id=None, conversation_id=None, name=None, description=None, style="openai")

Produces a tool definition dict you can pass straight into an OpenAI or Anthropic tool-calling loop. The returned dict carries the JSON schema, a scope-appropriate description, and a bound async handler coroutine the host runtime invokes when the LLM calls the tool. Scope identifiers (user_id, customer_id, conversation_id) are closed over inside the handler so the LLM cannot accidentally drop them. The per-user privacy filter holds regardless of what the model passes at call time. Prefer sdk.fetch(...) as the default integration; reach for as_tool only when the LLM genuinely needs agency over when context is fetched mid-reasoning.

Parameters

str

Which scope the tool fetches from. One of "conversation", "user", "customer", "client", or "unified" (cross-scope). Defaults to "user".

str

Closed-over user identifier. Required when scope="user", and strongly recommended for "conversation" and "unified" so the per-user privacy filter applies.

str

Closed-over customer identifier. Required when scope="customer". Required on B2B; auto-resolved on B2C. See B2C vs B2B.

str

Optional closed-over conversation identifier. When provided, the tool always fetches for this conversation; when omitted, the LLM supplies it per call. Must be a valid UUID registered via record_message.

str

Override the tool name exposed to the LLM. Defaults to synap_fetch_{scope}_context.

str

Override the tool description. Defaults to a scope-specific blurb that primes the LLM to call it for context retrieval.

str

Output dict shape. "openai" returns {"type": "function", "function": {...}}; "anthropic" returns {"name", "description", "input_schema"}. Defaults to "openai".

Returns

A tool definition dict shaped for the requested style. The dict always carries an async handler key with the bound coroutine; host runtimes that don’t use it can ignore it.

str

Present in "openai" style only. Always "function".

dict

Present in "openai" style only. Contains name, description, and parameters (the JSON schema).

str

Present in "anthropic" style. The tool name.

str

Present in "anthropic" style. The tool description.

dict

Present in "anthropic" style. JSON schema describing the tool’s call-time arguments.

Callable[..., Awaitable[dict]]

Async coroutine the host runtime should await with the LLM’s tool-call arguments. Returns the same shape sdk.fetch(...) produces.

Example

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()

# OpenAI-style tool, bound to a specific user.
tool = sdk.as_tool(scope="user", user_id="user-456")

# Hand the schema to the LLM, then route tool calls through the handler.
tool_call_args = {"search_query": ["dietary preferences"]}
result = await tool["handler"](**tool_call_args)
print(result["formatted_context"])

# Anthropic-style, cross-scope.
anthropic_tool = sdk.as_tool(
    scope="unified",
    user_id="user-456",
    customer_id="cust-789",
    style="anthropic",
)

Raises

InvalidInputError: when scope is not one of the accepted values, when scope="user" is requested without user_id, when scope="customer" is requested without customer_id, or when style is not "openai" or "anthropic".

See Error Codes for the full SDK exception hierarchy.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

Parameters

Returns

Example

Raises

See also

​Parameters

​Returns

​Example

​Raises

​See also

Parameters

Returns

Example

Raises

See also