"""The LangGraph agent: ``recall → agent ⇄ tools``.
* ``recall`` embeds the user message, loads matching facts, past exchanges and research, and
builds the per-turn context block (about 30-50 ms, so no speculation is needed).
* The system prompt is static and the context is attached only to the newest user message,
so Ollama can reuse its KV cache for the long, tool-laden prompt prefix (see prompts.py).
* ``agent`` calls the chat model with all tools bound. After ``max_tool_rounds`` tool rounds
the tools are unbound so the model has to answer.
* ``tools`` runs the requested tools; exceptions become error messages the model can read.
Conversation history is persisted per ``thread_id`` by the checkpointer. Events for the UI
are sent through the ``emit`` callback in ``config["configurable"]``.
"""
from __future__ import annotations
import asyncio
from collections.abc import Callable, Sequence
from datetime import datetime
from typing import Annotated, Any, TypedDict
from langchain_core.language_models import BaseChatModel
from langchain_core.messages import (
AIMessage,
AnyMessage,
HumanMessage,
SystemMessage,
ToolMessage,
)
from langchain_core.runnables import RunnableConfig
from langchain_core.tools import BaseTool
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from voicemate.agent.prompts import system_prompt, turn_context
from voicemate.agent.tools.base import emitter
from voicemate.agent.tools.memory_tools import format_recall
from voicemate.config import Config, LLMConfig
from voicemate.events import Lane, LaneState, StatusEvent, ToolEvent
from voicemate.memory.store import MemoryStore
#: Most recent history messages sent to the model (older ones stay in the checkpoint).
HISTORY_MESSAGES: int = 24
#: Appended to the turn context when the model went silent after using a tool.
ANSWER_NUDGE: str = "You have the tool results now: answer the user's question in full."
#: Appended to the turn context once the tool budget is exhausted.
NO_MORE_TOOLS: str = "Tool budget for this turn is used up: answer now with what you have."
[docs]
class AgentState(TypedDict):
"""Graph state.
Attributes:
messages: Conversation history (appended through the ``add_messages`` reducer).
lang: Reply language of the current turn.
context: Per-turn context block (time, language, memories) for the newest message.
tool_rounds: Tool rounds used in the current turn.
"""
messages: Annotated[list[AnyMessage], add_messages]
lang: str
context: str
tool_rounds: int
[docs]
def make_chat_model(
config: LLMConfig, model: str | None = None
) -> BaseChatModel: # pragma: no cover - needs Ollama
"""The Ollama chat model with thinking disabled (latency matters more for voice).
Args:
config: LLM settings.
model: Model tag; defaults to the preferred profile's model.
"""
from langchain_ollama import ChatOllama
return ChatOllama(
model=model or config.model,
temperature=config.temperature,
num_ctx=config.num_ctx,
keep_alive=config.keep_alive,
reasoning=False,
)
[docs]
def recent_history(messages: Sequence[AnyMessage], limit: int = HISTORY_MESSAGES) -> list:
"""The last ``limit`` messages, starting at a user message.
Starting at a user message keeps tool results together with the call that produced them.
"""
recent = list(messages[-limit:])
for i, message in enumerate(recent):
if isinstance(message, HumanMessage):
return recent[i:]
return recent
def _is_empty(message: Any) -> bool:
"""True for a reply with neither text nor tool calls."""
return not getattr(message, "tool_calls", None) and not str(message.content).strip()
[docs]
def with_context(messages: list[AnyMessage], context: str) -> list[AnyMessage]:
"""Copy of ``messages`` whose newest user message is prefixed with ``context``."""
out = list(messages)
for i in range(len(out) - 1, -1, -1):
message = out[i]
if isinstance(message, HumanMessage):
out[i] = HumanMessage(f"{context}\n\n{message.content}", id=message.id)
break
return out
[docs]
async def warm_up(llm: BaseChatModel, tools: list[BaseTool], config: Config) -> None:
"""Prefill the static prompt prefix so the first real turn hits Ollama's KV cache."""
messages = [
SystemMessage(system_prompt(config)),
HumanMessage(f"{turn_context('en', datetime.now().astimezone())}\n\nHi"),
]
await llm.bind_tools(tools).ainvoke(messages)
[docs]
def build_graph(
llm: BaseChatModel,
tools: list[BaseTool],
config: Config,
memory: MemoryStore | None = None,
checkpointer: Any = None,
now: Callable[[], datetime] = lambda: datetime.now().astimezone(),
) -> Any:
"""Compile the agent graph.
Args:
llm: Chat model supporting tool calling.
tools: Tools to bind.
config: Application config.
memory: Long-term memory used by the recall node (skipped when None).
checkpointer: LangGraph checkpointer for per-thread history.
now: Clock for the turn context.
Returns:
The compiled graph.
"""
settings = config # node functions receive the LangGraph run config as ``config``
with_tools = llm.bind_tools(tools)
max_rounds = settings.llm.max_tool_rounds
async def recall(state: AgentState, config: RunnableConfig) -> dict[str, Any]:
emit = emitter(config)
user = next((m for m in reversed(state["messages"]) if isinstance(m, HumanMessage)), None)
text = ""
if memory is not None and user is not None:
emit(StatusEvent(Lane.RECALLING, LaneState.ACTIVE))
found = await asyncio.to_thread(memory.recall, str(user.content))
text = "" if found.is_empty else format_recall(found)
emit(StatusEvent(Lane.RECALLING, LaneState.DONE))
lang = state.get("lang", settings.assistant.default_language)
context = turn_context(lang, now(), text)
return {"context": context, "tool_rounds": 0}
async def agent(state: AgentState, config: RunnableConfig) -> dict[str, Any]:
emit = emitter(config)
rounds = state.get("tool_rounds", 0)
context = state.get("context", "")
model = with_tools
if rounds >= max_rounds:
context = f"{context}\n{NO_MORE_TOOLS}"
model = llm
history = with_context(recent_history(state["messages"]), context)
messages = [SystemMessage(system_prompt(settings)), *history]
response = await model.ainvoke(messages, config)
if rounds and _is_empty(response):
# Small local models sometimes stop without answering after a tool round
# (observed with gemma4:e4b); ask once more instead of leaving the user hanging.
nudged = with_context(recent_history(state["messages"]), f"{context}\n{ANSWER_NUDGE}")
response = await model.ainvoke(
[SystemMessage(system_prompt(settings)), *nudged], config
)
calls = getattr(response, "tool_calls", None) or []
for call in calls:
emit(ToolEvent(call["name"], "start", dict(call.get("args", {}))))
return {"messages": [response], "tool_rounds": rounds + (1 if calls else 0)}
def route(state: AgentState) -> str:
last = state["messages"][-1]
return "tools" if isinstance(last, AIMessage) and last.tool_calls else END
# ty cannot yet match a TypedDict class against LangGraph's TypedDictLike protocol bound.
graph = StateGraph(AgentState) # ty: ignore[invalid-argument-type]
graph.add_node("recall", recall)
graph.add_node("agent", agent)
tool_node = ToolNode(tools, handle_tool_errors=True)
async def run_tools(state: AgentState, config: RunnableConfig) -> dict[str, Any]:
result = await tool_node.ainvoke(state, config)
# Successful tools report their own result; failed ones are closed here so the UI's
# tool lane and activity trace never hang on an error.
emit = emitter(config)
for message in result.get("messages", []):
if isinstance(message, ToolMessage) and message.status == "error":
summary = f"failed: {str(message.content)[:80]}"
emit(ToolEvent(message.name or "tool", "end", summary=summary))
return result
graph.add_node("tools", run_tools)
graph.add_edge(START, "recall")
graph.add_edge("recall", "agent")
graph.add_conditional_edges("agent", route, ["tools", END])
graph.add_edge("tools", "agent")
return graph.compile(checkpointer=checkpointer)