Python API - loom

Basic Setup

import asyncio
from loom import Loom, LoomConfig
from loom.prompts import default_cm_prompt, DEFAULT_CHATBOT_PROMPT

config = LoomConfig.from_file()  # auto-resolves config path

Using a Preset Template

The recommended way to get started:

loom = (
    Loom(config)
    .from_template("general")
    .cm_prompt(default_cm_prompt)
    .chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)

Defining Schema Manually

For custom schema structures:

from loom import UniversalSchemaDomain

user = UniversalSchemaDomain("user_profile")
user.create_field("identity.name", "", "User's name")
user.create_field("preferences.hobbies", "", "Hobbies and interests")

loom = (
    Loom(config)
    .register(user)
    .cm_prompt(default_cm_prompt)
    .chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)

Build Memory

Process any text into structured memory:

asyncio.run(loom.build("""
    [user]: I'm Bob, I love hiking and sushi.
    [assistant]: Great taste, Bob!
""", session_id="bob"))

Chat with Memory

Generate responses grounded in schema data:

result = asyncio.run(loom.chat("What food do I like?", session_id="bob"))
print(result["reply"])  # "You mentioned that you love sushi!"

chat() returns a dict with the following keys:

Key	Type	Description
`reply`	`str`	The chatbot response
`schema_updated`	`bool`	Whether schema auto-update was triggered this round
`context_rounds`	`int`	Number of chat rounds included as context
`total_rounds`	`int`	Total chat rounds in this session
`memory_injected`	`bool`	Whether schema memory was injected (context window exceeded)
`request_data`	`dict`	The system prompt and messages sent to the LLM

Listen Mode

listen() provides automatic periodic memory extraction — it accumulates chat history, runs the CM agent in build mode every N turns, and recalls schema data every turn:

config = LoomConfig.from_file()
config.build_every_n_turns = 3  # run build CM every 3 turns

loom = (
    Loom(config)
    .from_template("general")
    .cm_prompt(default_cm_prompt)
    .chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)

# listen() returns the chatbot reply string directly
reply = asyncio.run(loom.listen("I'm Bob, I love hiking.", session_id="bob"))
print(reply)

Unlike chat(), listen() returns a plain string (not a dict). Build triggers when turn_number % build_every_n_turns == 0.

Selective Recall

recall() runs the CM agent in QA mode to retrieve only the schema fields relevant to a message:

result = asyncio.run(loom.recall("What food do I like?", session_id="bob"))
print(result["recalled"])      # Formatted schema excerpt
print(result["is_selective"])  # True if the CM agent found relevant data

Dynamic Schema Update

Enable automatic schema updates during chat:

config = LoomConfig.from_file()
config.build_every_n_turns = 3  # update schema every 3 rounds

loom = (
    Loom(config)
    .from_template("general")
    .cm_prompt(default_cm_prompt)
    .chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)

# chat() returns a dict with reply and schema_updated flag
result = asyncio.run(loom.chat("I just got promoted to Senior Engineer!", session_id="bob"))
print(result["reply"])            # The chatbot response
print(result["schema_updated"])   # True if schema was auto-updated this round

# Manual trigger: update schema from last 10 rounds of chat
asyncio.run(loom.update_schema_from_chat(session_id="bob", rounds=10))

Plugins & Custom Tools

loom = (
    Loom(config)
    .from_template("general")
    .cm_prompt(default_cm_prompt)
    .chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
    .use(MyRAGPlugin("http://localhost:9000"))   # add plugin hooks
    .tools(my_custom_tools_builder)              # add custom SCP tools
)

See Plugins for the full plugin protocol.

Config Loading

Multiple ways to load configuration:

from loom import LoomConfig

config = LoomConfig.from_file()                      # auto-resolve + env vars
config = LoomConfig.from_file("configs/loom.yaml")   # explicit path
config = LoomConfig.from_env()                        # env vars only
config = LoomConfig(model="gpt-5.4")                  # direct construction

Custom CM Prompt

Override the default CM agent behavior:

def my_cm_prompt(state, registry):
    schema_overview = registry.inspect_all(max_depth=state.get("inspect_max_depth", 3))
    return f"""You are a medical records agent.

Available schemas:
{schema_overview}

Extract: diagnoses, medications, allergies, vitals.
When done: {{"continue": false}}"""

loom = Loom(config).cm_prompt(my_cm_prompt).chatbot_prompt(my_template)

​Basic Setup

​Using a Preset Template

​Defining Schema Manually

​Build Memory

​Chat with Memory

​Listen Mode

​Selective Recall

​Dynamic Schema Update

​Plugins & Custom Tools

​Config Loading

​Custom CM Prompt