mainspring 3.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. mainspring/__init__.py +32 -0
  2. mainspring/checkpoint/__init__.py +30 -0
  3. mainspring/checkpoint/codec.py +40 -0
  4. mainspring/checkpoint/postgres.py +89 -0
  5. mainspring/checkpoint/redis.py +44 -0
  6. mainspring/checkpoint/sqlite.py +93 -0
  7. mainspring/context.py +61 -0
  8. mainspring/core/__init__.py +29 -0
  9. mainspring/core/checkpointer.py +38 -0
  10. mainspring/core/nodes/__init__.py +3 -0
  11. mainspring/core/nodes/decide.py +102 -0
  12. mainspring/core/nodes/execute.py +156 -0
  13. mainspring/core/nodes/observe.py +38 -0
  14. mainspring/core/nodes/plan.py +63 -0
  15. mainspring/core/resilience.py +97 -0
  16. mainspring/core/runtime.py +528 -0
  17. mainspring/core/state.py +42 -0
  18. mainspring/evaluation/__init__.py +9 -0
  19. mainspring/evaluation/golden.py +57 -0
  20. mainspring/events/__init__.py +19 -0
  21. mainspring/events/events.py +83 -0
  22. mainspring/knowledge/__init__.py +3 -0
  23. mainspring/knowledge/plugin.py +69 -0
  24. mainspring/llm/__init__.py +33 -0
  25. mainspring/llm/base.py +26 -0
  26. mainspring/llm/cost.py +101 -0
  27. mainspring/llm/embedder.py +57 -0
  28. mainspring/llm/litellm_gateway.py +116 -0
  29. mainspring/llm/replay.py +91 -0
  30. mainspring/llm/routing.py +115 -0
  31. mainspring/llm/stream.py +56 -0
  32. mainspring/llm/structured.py +32 -0
  33. mainspring/log.py +43 -0
  34. mainspring/memory/__init__.py +6 -0
  35. mainspring/memory/consolidator.py +84 -0
  36. mainspring/memory/manager.py +50 -0
  37. mainspring/memory/reflect.py +46 -0
  38. mainspring/memory/working.py +36 -0
  39. mainspring/observability/__init__.py +11 -0
  40. mainspring/observability/metrics.py +44 -0
  41. mainspring/observability/trace.py +68 -0
  42. mainspring/plugins/__init__.py +4 -0
  43. mainspring/plugins/base.py +48 -0
  44. mainspring/plugins/manifest.py +32 -0
  45. mainspring/plugins/registry.py +90 -0
  46. mainspring/ports.py +389 -0
  47. mainspring/py.typed +0 -0
  48. mainspring/security/__init__.py +64 -0
  49. mainspring/skills/__init__.py +3 -0
  50. mainspring/skills/agent_skill.py +24 -0
  51. mainspring/skills/base.py +64 -0
  52. mainspring/skills/flow_skill.py +18 -0
  53. mainspring/skills/function_skill.py +100 -0
  54. mainspring/skills/manager.py +44 -0
  55. mainspring/skills/prompt_skill.py +24 -0
  56. mainspring/tools/__init__.py +13 -0
  57. mainspring/tools/_http.py +27 -0
  58. mainspring/tools/base.py +28 -0
  59. mainspring/tools/builtin/__init__.py +4 -0
  60. mainspring/tools/builtin/calculator.py +60 -0
  61. mainspring/tools/builtin/http.py +28 -0
  62. mainspring/tools/decorator.py +78 -0
  63. mainspring/tools/http_openapi.py +92 -0
  64. mainspring/tools/mcp.py +86 -0
  65. mainspring/tools/registry.py +41 -0
  66. mainspring-3.3.0.dist-info/METADATA +434 -0
  67. mainspring-3.3.0.dist-info/RECORD +69 -0
  68. mainspring-3.3.0.dist-info/WHEEL +4 -0
  69. mainspring-3.3.0.dist-info/licenses/LICENSE +21 -0
mainspring/__init__.py ADDED
@@ -0,0 +1,32 @@
1
+ """Mainspring — a business-agnostic agent runtime."""
2
+
3
+ import logging
4
+
5
+ __version__ = "3.3.0"
6
+
7
+ from mainspring.context import SlidingWindowContext # noqa: E402
8
+ from mainspring.core.runtime import ( # noqa: E402
9
+ AgentDefinition,
10
+ AgentRuntime,
11
+ RunContext,
12
+ RunResult,
13
+ RuntimeConfig,
14
+ RuntimeDeps,
15
+ Step,
16
+ )
17
+
18
+ __all__ = [
19
+ "__version__",
20
+ "AgentRuntime",
21
+ "AgentDefinition",
22
+ "RunContext",
23
+ "RunResult",
24
+ "RuntimeConfig",
25
+ "RuntimeDeps",
26
+ "SlidingWindowContext",
27
+ "Step",
28
+ ]
29
+
30
+ # Library best practice: attach a NullHandler so an unconfigured host doesn't emit
31
+ # "No handlers could be found" warnings from our loggers.
32
+ logging.getLogger("mainspring").addHandler(logging.NullHandler())
@@ -0,0 +1,30 @@
1
+ """Official Checkpointer implementations (V3.3): SQLite, Redis, PostgreSQL.
2
+
3
+ All three persist the same ``{"schema_version": N, "state": ...}`` envelope (`codec.py`)
4
+ and satisfy the ``mainspring.ports.Checkpointer`` protocol:
5
+
6
+ - ``SQLiteCheckpointer`` — zero-configuration, zero-dependency, single file. The default
7
+ for standalone hosts that need durability without any infrastructure.
8
+ - ``RedisCheckpointer`` — cross-process / cross-instance over a host-supplied
9
+ `redis.asyncio.Redis` client (no new dependency; the Working Brain uses the same pattern).
10
+ - ``PostgresCheckpointer`` — durable snapshots over a host-supplied DBAPI 2.0 connection;
11
+ the framework never imports a PG driver. Hosts that need the snapshot colocated with
12
+ their own run row (atomic status + snapshot) should implement the port themselves.
13
+
14
+ ``InMemoryCheckpointer`` remains the test default and lives in
15
+ ``mainspring.core.checkpointer``.
16
+ """
17
+
18
+ from mainspring.checkpoint.codec import SCHEMA_VERSION, decode, encode
19
+ from mainspring.checkpoint.postgres import PostgresCheckpointer
20
+ from mainspring.checkpoint.redis import RedisCheckpointer
21
+ from mainspring.checkpoint.sqlite import SQLiteCheckpointer
22
+
23
+ __all__ = [
24
+ "SQLiteCheckpointer",
25
+ "RedisCheckpointer",
26
+ "PostgresCheckpointer",
27
+ "SCHEMA_VERSION",
28
+ "encode",
29
+ "decode",
30
+ ]
@@ -0,0 +1,40 @@
1
+ """Shared checkpoint serialization (V3.3): the one codec every backend uses.
2
+
3
+ State dicts are wrapped in a ``{"schema_version": N, "state": {...}}`` envelope so a
4
+ checkpoint written by an older framework version is *detected*, not silently resumed
5
+ with missing or misinterpreted fields. ``decode`` raises ``ValueError`` on corrupt JSON
6
+ or an unsupported version — resuming a half-approved run from a wrong snapshot is worse
7
+ than failing loudly.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+
14
+ SCHEMA_VERSION = 1
15
+
16
+
17
+ def encode(state: dict) -> str:
18
+ return json.dumps(
19
+ {"schema_version": SCHEMA_VERSION, "state": state},
20
+ ensure_ascii=False,
21
+ default=str,
22
+ )
23
+
24
+
25
+ def decode(raw: str | bytes) -> dict:
26
+ if isinstance(raw, bytes):
27
+ raw = raw.decode("utf-8")
28
+ try:
29
+ envelope = json.loads(raw)
30
+ except (json.JSONDecodeError, TypeError) as exc:
31
+ raise ValueError("checkpoint payload is not valid JSON") from exc
32
+ if not isinstance(envelope, dict) or envelope.get("schema_version") != SCHEMA_VERSION:
33
+ raise ValueError(
34
+ f"checkpoint schema_version {envelope.get('schema_version') if isinstance(envelope, dict) else '?'!r} "
35
+ f"is not supported (current: {SCHEMA_VERSION})"
36
+ )
37
+ return envelope["state"]
38
+
39
+
40
+ __all__ = ["SCHEMA_VERSION", "encode", "decode"]
@@ -0,0 +1,89 @@
1
+ """PostgreSQL Checkpointer (V3.3): durable snapshots for hosts that already run Postgres.
2
+
3
+ The framework stays dependency-free: it accepts any DBAPI 2.0 connection (``psycopg2``,
4
+ ``psycopg``, …) supplied by the host, so importing ``mainspring`` never requires a PG
5
+ driver. All DB work runs on a worker thread; the table is created lazily on first use.
6
+
7
+ This keeps its own ``checkpoints`` table and is *not* a substitute for colocating the
8
+ snapshot on the host's run row with an atomic status flip — hosts that need
9
+ "status + snapshot in one transaction" should implement the port themselves (the
10
+ business layer's `DbCheckpointer` does exactly that).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import asyncio
16
+ from datetime import datetime, timezone
17
+
18
+ from mainspring.checkpoint.codec import SCHEMA_VERSION, decode, encode
19
+
20
+ _TABLE_DDL = """
21
+ CREATE TABLE IF NOT EXISTS checkpoints (
22
+ run_id TEXT PRIMARY KEY,
23
+ state TEXT NOT NULL,
24
+ schema_version INTEGER NOT NULL,
25
+ updated_at TEXT NOT NULL
26
+ )
27
+ """
28
+
29
+ _UPSERT_SQL = """
30
+ INSERT INTO checkpoints (run_id, state, schema_version, updated_at)
31
+ VALUES (%s, %s, %s, %s)
32
+ ON CONFLICT (run_id) DO UPDATE SET
33
+ state = EXCLUDED.state,
34
+ schema_version = EXCLUDED.schema_version,
35
+ updated_at = EXCLUDED.updated_at
36
+ """
37
+
38
+
39
+ class PostgresCheckpointer:
40
+ """Persists run state snapshots over a host-supplied DBAPI 2.0 connection."""
41
+
42
+ def __init__(self, conn) -> None:
43
+ self._conn = conn
44
+ self._ready = False
45
+ self._lock = asyncio.Lock()
46
+
47
+ def _execute(self, sql: str, params: tuple = ()):
48
+ cur = self._conn.cursor()
49
+ try:
50
+ cur.execute(sql, params)
51
+ self._conn.commit()
52
+ return cur
53
+ except Exception:
54
+ self._conn.rollback()
55
+ raise
56
+
57
+ async def _ensure_table(self) -> None:
58
+ async with self._lock:
59
+ if self._ready:
60
+ return
61
+ await asyncio.to_thread(self._execute, _TABLE_DDL)
62
+ self._ready = True
63
+
64
+ async def save(self, run_id: str, state: dict) -> None:
65
+ await self._ensure_table()
66
+ now = datetime.now(timezone.utc).isoformat()
67
+ await asyncio.to_thread(self._execute, _UPSERT_SQL, (run_id, encode(state), SCHEMA_VERSION, now))
68
+
69
+ async def load(self, run_id: str) -> dict | None:
70
+ await self._ensure_table()
71
+ cur = await asyncio.to_thread(
72
+ self._execute, "SELECT state FROM checkpoints WHERE run_id = %s", (run_id,)
73
+ )
74
+ row = cur.fetchone()
75
+ return None if row is None else decode(row[0])
76
+
77
+ async def delete(self, run_id: str) -> None:
78
+ await self._ensure_table()
79
+ await asyncio.to_thread(self._execute, "DELETE FROM checkpoints WHERE run_id = %s", (run_id,))
80
+
81
+ async def list_runs(self) -> list[str]:
82
+ await self._ensure_table()
83
+ cur = await asyncio.to_thread(
84
+ self._execute, "SELECT run_id FROM checkpoints ORDER BY run_id"
85
+ )
86
+ return [row[0] for row in cur.fetchall()]
87
+
88
+
89
+ __all__ = ["PostgresCheckpointer"]
@@ -0,0 +1,44 @@
1
+ """Redis Checkpointer (V3.3): cross-process, cross-instance snapshots.
2
+
3
+ Takes a `redis.asyncio.Redis` client (already a framework dependency — the Working Brain
4
+ uses the same pattern), so no new dependency is introduced. Keys are ``{prefix}{run_id}``
5
+ with the state codec envelope as the value.
6
+
7
+ ``ttl_seconds`` defaults to ``None`` (persist forever): a paused run waiting for human
8
+ approval must stay resumable for as long as the approval takes, and an expiry that
9
+ silently drops it would turn a late approval into a lost run. Pass a TTL only when you
10
+ have a separate cleanup policy for terminal runs.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from mainspring.checkpoint.codec import decode, encode
16
+
17
+
18
+ class RedisCheckpointer:
19
+ """Persists run state snapshots in Redis."""
20
+
21
+ def __init__(self, redis, *, prefix: str = "cp:", ttl_seconds: int | None = None) -> None:
22
+ self._redis = redis
23
+ self._prefix = prefix
24
+ self._ttl = ttl_seconds
25
+
26
+ def _key(self, run_id: str) -> str:
27
+ return f"{self._prefix}{run_id}"
28
+
29
+ async def save(self, run_id: str, state: dict) -> None:
30
+ await self._redis.set(self._key(run_id), encode(state), ex=self._ttl)
31
+
32
+ async def load(self, run_id: str) -> dict | None:
33
+ raw = await self._redis.get(self._key(run_id))
34
+ return None if raw is None else decode(raw)
35
+
36
+ async def delete(self, run_id: str) -> None:
37
+ await self._redis.delete(self._key(run_id))
38
+
39
+ async def list_runs(self) -> list[str]:
40
+ keys = [key async for key in self._redis.scan_iter(match=f"{self._prefix}*")]
41
+ return sorted(key[len(self._prefix):] for key in keys)
42
+
43
+
44
+ __all__ = ["RedisCheckpointer"]
@@ -0,0 +1,93 @@
1
+ """SQLite Checkpointer (V3.3): durable, zero-configuration, zero-dependency.
2
+
3
+ One file, one table, WAL mode. Each operation opens its own connection (the checkpoint
4
+ path is low-frequency, so per-call connections are simpler and safer than pooling);
5
+ SQLite's file locking handles cross-process safety. ``:memory:`` is rejected explicitly —
6
+ with per-call connections it would silently open a fresh empty database every call, which
7
+ is exactly the "state lost on restart" trap this class exists to fix.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ import sqlite3
14
+ import threading
15
+ from datetime import datetime, timezone
16
+ from pathlib import Path
17
+
18
+ from mainspring.checkpoint.codec import SCHEMA_VERSION, decode, encode
19
+
20
+ _TABLE_DDL = """
21
+ CREATE TABLE IF NOT EXISTS checkpoints (
22
+ run_id TEXT PRIMARY KEY,
23
+ state TEXT NOT NULL,
24
+ schema_version INTEGER NOT NULL,
25
+ updated_at TEXT NOT NULL
26
+ )
27
+ """
28
+
29
+ _UPSERT_SQL = """
30
+ INSERT INTO checkpoints (run_id, state, schema_version, updated_at)
31
+ VALUES (?, ?, ?, ?)
32
+ ON CONFLICT (run_id) DO UPDATE SET
33
+ state = excluded.state,
34
+ schema_version = excluded.schema_version,
35
+ updated_at = excluded.updated_at
36
+ """
37
+
38
+
39
+ class SQLiteCheckpointer:
40
+ """Persists run state snapshots in a single SQLite file (stdlib `sqlite3`)."""
41
+
42
+ def __init__(self, path: str | Path) -> None:
43
+ self._path = str(path)
44
+ if self._path == ":memory:":
45
+ raise ValueError(
46
+ ":memory: is not durable — each call opens its own connection, so it would "
47
+ "start empty every time. Pass a file path instead."
48
+ )
49
+ self._lock = threading.Lock()
50
+
51
+ def _run_sync(self, fn):
52
+ with self._lock:
53
+ conn = sqlite3.connect(self._path)
54
+ try:
55
+ conn.execute("PRAGMA busy_timeout=5000")
56
+ conn.execute("PRAGMA journal_mode=WAL")
57
+ conn.execute(_TABLE_DDL)
58
+ return fn(conn)
59
+ finally:
60
+ conn.close()
61
+
62
+ async def save(self, run_id: str, state: dict) -> None:
63
+ payload = encode(state)
64
+ now = datetime.now(timezone.utc).isoformat()
65
+
66
+ def _save(conn) -> None:
67
+ conn.execute(_UPSERT_SQL, (run_id, payload, SCHEMA_VERSION, now))
68
+ conn.commit()
69
+
70
+ await asyncio.to_thread(self._run_sync, _save)
71
+
72
+ async def load(self, run_id: str) -> dict | None:
73
+ def _load(conn):
74
+ row = conn.execute("SELECT state FROM checkpoints WHERE run_id = ?", (run_id,)).fetchone()
75
+ return None if row is None else decode(row[0])
76
+
77
+ return await asyncio.to_thread(self._run_sync, _load)
78
+
79
+ async def delete(self, run_id: str) -> None:
80
+ def _delete(conn) -> None:
81
+ conn.execute("DELETE FROM checkpoints WHERE run_id = ?", (run_id,))
82
+ conn.commit()
83
+
84
+ await asyncio.to_thread(self._run_sync, _delete)
85
+
86
+ async def list_runs(self) -> list[str]:
87
+ def _list(conn):
88
+ return [row[0] for row in conn.execute("SELECT run_id FROM checkpoints ORDER BY run_id")]
89
+
90
+ return await asyncio.to_thread(self._run_sync, _list)
91
+
92
+
93
+ __all__ = ["SQLiteCheckpointer"]
mainspring/context.py ADDED
@@ -0,0 +1,61 @@
1
+ """Default ContextManager (v2.1): sliding window + tool-result truncation.
2
+
3
+ Zero dependencies and side-effect free — it satisfies the ``ports.ContextManager``
4
+ protocol so the runtime can compact long histories before every Decide call. A host that
5
+ wants summarization instead of truncation implements the same protocol and captures its
6
+ own ``LLMGateway``; this default only ever drops or shortens messages.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+
12
+ class SlidingWindowContext:
13
+ """Keep the head system messages plus the newest `max_messages` turns.
14
+
15
+ Dropping from the front can strand tool messages whose assistant tool-call parent was
16
+ dropped (which OpenAI-compatible APIs reject), so the cut point always advances past
17
+ leading tool messages. Oversized tool results are truncated in place even when the
18
+ window is not exceeded — a single huge tool output is the most common context blowup.
19
+ """
20
+
21
+ def __init__(self, max_messages: int = 40, max_tool_chars: int = 4000) -> None:
22
+ self._max_messages = max_messages
23
+ self._max_tool_chars = max_tool_chars
24
+
25
+ def fit(self, messages: list[dict]) -> list[dict]:
26
+ out = [self._truncate(m) for m in messages]
27
+ if len(out) <= self._max_messages:
28
+ return out
29
+
30
+ head = 0
31
+ while head < len(out) and out[head].get("role") == "system":
32
+ head += 1
33
+ if head >= len(out):
34
+ return out # all system messages — nothing droppable
35
+
36
+ # keep `head` system messages + newest tail; cut >= what makes the total fit
37
+ cut = max(head, len(out) + head - self._max_messages)
38
+ while cut < len(out) and out[cut].get("role") == "tool":
39
+ cut += 1 # never strand a tool message at the tail's front
40
+ if cut <= head:
41
+ return out
42
+ marker = {
43
+ "role": "system",
44
+ "content": f"[{cut - head} earlier messages omitted by context compaction]",
45
+ }
46
+ return out[:head] + [marker] + out[cut:]
47
+
48
+ def _truncate(self, message: dict) -> dict:
49
+ if message.get("role") != "tool":
50
+ return message
51
+ content = message.get("content")
52
+ if not isinstance(content, str) or len(content) <= self._max_tool_chars:
53
+ return message
54
+ trimmed = dict(message)
55
+ trimmed["content"] = content[: self._max_tool_chars] + (
56
+ f"…[truncated {len(content) - self._max_tool_chars} chars]"
57
+ )
58
+ return trimmed
59
+
60
+
61
+ __all__ = ["SlidingWindowContext"]
@@ -0,0 +1,29 @@
1
+ from mainspring.core.checkpointer import InMemoryCheckpointer
2
+ from mainspring.core.resilience import CircuitBreaker, CircuitOpenError, RetryPolicy, run_with_retry
3
+ from mainspring.core.runtime import (
4
+ AgentDefinition,
5
+ AgentRuntime,
6
+ RunContext,
7
+ RunResult,
8
+ RuntimeConfig,
9
+ RuntimeDeps,
10
+ Step,
11
+ )
12
+ from mainspring.core.state import AgentState, PlanStep
13
+
14
+ __all__ = [
15
+ "AgentState",
16
+ "PlanStep",
17
+ "AgentRuntime",
18
+ "AgentDefinition",
19
+ "RunContext",
20
+ "RunResult",
21
+ "RuntimeConfig",
22
+ "RuntimeDeps",
23
+ "Step",
24
+ "InMemoryCheckpointer",
25
+ "RetryPolicy",
26
+ "CircuitBreaker",
27
+ "CircuitOpenError",
28
+ "run_with_retry",
29
+ ]
@@ -0,0 +1,38 @@
1
+ """Zero-dependency in-memory Checkpointer (V0.3).
2
+
3
+ Used by tests and single-process deployments. Durable deployments use the official
4
+ implementations in ``mainspring.checkpoint`` (SQLite / Redis / PostgreSQL), or implement
5
+ the ``mainspring.ports.Checkpointer`` protocol themselves and pass it via
6
+ ``RuntimeDeps.checkpointer``.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import copy
12
+
13
+ from mainspring.ports import Checkpointer
14
+
15
+
16
+ class InMemoryCheckpointer:
17
+ """Stores run state keyed by ``run_id``. State is deep-copied on save/load so the
18
+ runtime's later mutations never corrupt a saved snapshot."""
19
+
20
+ def __init__(self) -> None:
21
+ self._store: dict[str, dict] = {}
22
+
23
+ async def save(self, run_id: str, state: dict) -> None:
24
+ self._store[run_id] = copy.deepcopy(state)
25
+
26
+ async def load(self, run_id: str) -> dict | None:
27
+ state = self._store.get(run_id)
28
+ return copy.deepcopy(state) if state is not None else None
29
+
30
+ async def delete(self, run_id: str) -> None:
31
+ self._store.pop(run_id, None)
32
+
33
+ async def list_runs(self) -> list[str]:
34
+ return list(self._store)
35
+
36
+
37
+ # Re-export the protocol alongside the default implementation for convenience.
38
+ __all__ = ["InMemoryCheckpointer", "Checkpointer"]
@@ -0,0 +1,3 @@
1
+ from mainspring.core.nodes import decide, execute, observe, plan
2
+
3
+ __all__ = ["plan", "decide", "execute", "observe"]
@@ -0,0 +1,102 @@
1
+ import json
2
+ import logging
3
+ from collections.abc import Awaitable, Callable
4
+
5
+ from mainspring.core.state import FINISH, AgentState
6
+ from mainspring.ports import ChatChunk, LLMGateway, LLMResponse
7
+ from mainspring.llm.stream import accumulate_response
8
+
9
+ logger = logging.getLogger(__name__)
10
+
11
+ _DEFAULT_SYSTEM = "You are a general-purpose assistant. Call the calculator tool for arithmetic problems."
12
+
13
+ # Async callable receiving each content delta as it arrives (token-level event emission).
14
+ DeltaCallback = Callable[[str], Awaitable[None]]
15
+
16
+
17
+ async def run_decide(
18
+ state: AgentState,
19
+ llm: LLMGateway,
20
+ model: str,
21
+ tool_schemas: list[dict],
22
+ system_prompt: str | None = None,
23
+ on_delta: DeltaCallback | None = None,
24
+ ) -> dict:
25
+ system = system_prompt or _DEFAULT_SYSTEM
26
+ messages: list[dict] = [{"role": "system", "content": system}]
27
+
28
+ plan = state.get("plan") or []
29
+ if plan:
30
+ plan_text = "\n".join(f"{s['id']}. {s['description']}" for s in plan)
31
+ messages.append({"role": "system", "content": f"Current plan:\n{plan_text}"})
32
+
33
+ # Recalled long-term memories / knowledge fallback must reach the LLM even when the
34
+ # (optional) Plan node is disabled — Decide is the only guaranteed LLM call.
35
+ memory_ctx = state.get("memory_ctx") or []
36
+ if memory_ctx:
37
+ ctx_text = "\n".join(m.get("content", "") for m in memory_ctx)
38
+ messages.append(
39
+ {"role": "system", "content": f"Relevant past memories about this user/task:\n{ctx_text}"}
40
+ )
41
+
42
+ messages.extend(state.get("messages") or [])
43
+
44
+ if on_delta is not None and hasattr(llm, "chat_stream"):
45
+ resp = await _stream_response(llm, messages, model, tool_schemas or None, on_delta)
46
+ else:
47
+ resp = await llm.chat(messages=messages, model=model, tools=tool_schemas or None)
48
+
49
+ if resp.tool_calls:
50
+ tool_calls = [
51
+ {"id": tc.id or f"call_{tc.name}", "name": tc.name, "arguments": tc.arguments}
52
+ for tc in resp.tool_calls
53
+ ]
54
+ messages_history = list(state.get("messages") or [])
55
+ messages_history.append({
56
+ "role": "assistant",
57
+ "content": resp.content,
58
+ "tool_calls": [
59
+ {
60
+ "id": tc["id"],
61
+ "type": "function",
62
+ "function": {
63
+ "name": tc["name"],
64
+ "arguments": json.dumps(tc["arguments"], ensure_ascii=False),
65
+ },
66
+ }
67
+ for tc in tool_calls
68
+ ],
69
+ })
70
+ first = tool_calls[0]
71
+ logger.debug("decide: action=%s (%d tool calls)", first["name"], len(tool_calls))
72
+ return {
73
+ "action": first["name"],
74
+ "action_input": first["arguments"],
75
+ "tool_call_id": first["id"],
76
+ "tool_calls": tool_calls,
77
+ "messages": messages_history,
78
+ "token_usage": resp.usage.model_dump(),
79
+ }
80
+
81
+ logger.debug("decide: finish")
82
+ return {"action": FINISH, "result": resp.content or "", "token_usage": resp.usage.model_dump()}
83
+
84
+
85
+ async def _stream_response(
86
+ llm: LLMGateway,
87
+ messages: list[dict],
88
+ model: str,
89
+ tools: list[dict] | None,
90
+ on_delta: DeltaCallback,
91
+ ) -> LLMResponse:
92
+ """Consume a streaming chat, forwarding content deltas live, then fold to one response.
93
+
94
+ A retried Decide re-streams from scratch, so consumers must treat deltas as ephemeral
95
+ and the folded response as the only authoritative result.
96
+ """
97
+ chunks: list[ChatChunk] = []
98
+ async for chunk in llm.chat_stream(messages=messages, model=model, tools=tools):
99
+ chunks.append(chunk)
100
+ if chunk.content_delta:
101
+ await on_delta(chunk.content_delta)
102
+ return accumulate_response(chunks)