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.
- mainspring/__init__.py +32 -0
- mainspring/checkpoint/__init__.py +30 -0
- mainspring/checkpoint/codec.py +40 -0
- mainspring/checkpoint/postgres.py +89 -0
- mainspring/checkpoint/redis.py +44 -0
- mainspring/checkpoint/sqlite.py +93 -0
- mainspring/context.py +61 -0
- mainspring/core/__init__.py +29 -0
- mainspring/core/checkpointer.py +38 -0
- mainspring/core/nodes/__init__.py +3 -0
- mainspring/core/nodes/decide.py +102 -0
- mainspring/core/nodes/execute.py +156 -0
- mainspring/core/nodes/observe.py +38 -0
- mainspring/core/nodes/plan.py +63 -0
- mainspring/core/resilience.py +97 -0
- mainspring/core/runtime.py +528 -0
- mainspring/core/state.py +42 -0
- mainspring/evaluation/__init__.py +9 -0
- mainspring/evaluation/golden.py +57 -0
- mainspring/events/__init__.py +19 -0
- mainspring/events/events.py +83 -0
- mainspring/knowledge/__init__.py +3 -0
- mainspring/knowledge/plugin.py +69 -0
- mainspring/llm/__init__.py +33 -0
- mainspring/llm/base.py +26 -0
- mainspring/llm/cost.py +101 -0
- mainspring/llm/embedder.py +57 -0
- mainspring/llm/litellm_gateway.py +116 -0
- mainspring/llm/replay.py +91 -0
- mainspring/llm/routing.py +115 -0
- mainspring/llm/stream.py +56 -0
- mainspring/llm/structured.py +32 -0
- mainspring/log.py +43 -0
- mainspring/memory/__init__.py +6 -0
- mainspring/memory/consolidator.py +84 -0
- mainspring/memory/manager.py +50 -0
- mainspring/memory/reflect.py +46 -0
- mainspring/memory/working.py +36 -0
- mainspring/observability/__init__.py +11 -0
- mainspring/observability/metrics.py +44 -0
- mainspring/observability/trace.py +68 -0
- mainspring/plugins/__init__.py +4 -0
- mainspring/plugins/base.py +48 -0
- mainspring/plugins/manifest.py +32 -0
- mainspring/plugins/registry.py +90 -0
- mainspring/ports.py +389 -0
- mainspring/py.typed +0 -0
- mainspring/security/__init__.py +64 -0
- mainspring/skills/__init__.py +3 -0
- mainspring/skills/agent_skill.py +24 -0
- mainspring/skills/base.py +64 -0
- mainspring/skills/flow_skill.py +18 -0
- mainspring/skills/function_skill.py +100 -0
- mainspring/skills/manager.py +44 -0
- mainspring/skills/prompt_skill.py +24 -0
- mainspring/tools/__init__.py +13 -0
- mainspring/tools/_http.py +27 -0
- mainspring/tools/base.py +28 -0
- mainspring/tools/builtin/__init__.py +4 -0
- mainspring/tools/builtin/calculator.py +60 -0
- mainspring/tools/builtin/http.py +28 -0
- mainspring/tools/decorator.py +78 -0
- mainspring/tools/http_openapi.py +92 -0
- mainspring/tools/mcp.py +86 -0
- mainspring/tools/registry.py +41 -0
- mainspring-3.3.0.dist-info/METADATA +434 -0
- mainspring-3.3.0.dist-info/RECORD +69 -0
- mainspring-3.3.0.dist-info/WHEEL +4 -0
- 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,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)
|