create project

Author: liqiankun1111

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: ledger
+          POSTGRES_USER: ledger
+          POSTGRES_DB: ledger
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U ledger"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: ledger
+          MYSQL_DATABASE: ledger
+          MYSQL_USER: ledger
+          MYSQL_PASSWORD: ledger
+        ports: ["3306:3306"]
+        options: >-
+          --health-cmd "mysqladmin ping -h localhost -pledger"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    env:
+      AGENT_LEDGER_REDIS_URL: redis://localhost:6379/0
+      AGENT_LEDGER_POSTGRES_URL: postgresql+asyncpg://ledger:ledger@localhost:5432/ledger
+      AGENT_LEDGER_MYSQL_URL: mysql+asyncmy://ledger:ledger@localhost:3306/ledger
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: make lint
+      - run: make test
+

.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.worktree/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Agent Ledger contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

Makefile

@@ -0,0 +1,17 @@
+.PHONY: fix lint test build
+
+fix:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+lint:
+	uv run ruff format --check .
+	uv run ruff check .
+	uv run mypy
+
+test:
+	uv run pytest
+
+build:
+	uv build
+

README.md

@@ -0,0 +1,84 @@
+# Agent Ledger
+
+Agent Ledger is a framework-neutral event ledger for durable agent sessions. It records agent
+steps before model and tool execution, keeps causal links across distributed agent runs, and gives
+framework adapters enough facts to rebuild their own run context after a restart.
+
+The ledger is the source of truth for **what happened**. Recovery remains owned by the framework
+integration that understands its checkpoint and `RunContext` types.
+
+## Why another event log?
+
+Traditional logs and traces explain service execution. Agent Ledger adds agent-native invariants:
+
+- `Session` groups one end-to-end task across processes and agents.
+- `Run` is the optimistic-concurrency stream written by one agent loop.
+- `Step` is a logical unit; `Attempt` is one physical model or tool invocation.
+- requested events are committed before external calls, so interrupted calls remain visible.
+- `parent_run_id` and `caused_by_event_id` form a causal DAG without relying on timestamps.
+- trajectories such as ATIF are projections, not the durable source of truth.
+
+## Quick start
+
+```python
+from agent_ledger import Actor, SessionRecorder
+from agent_ledger.stores.memory import MemoryEventStore
+
+store = MemoryEventStore()
+recorder = SessionRecorder(
+    store=store,
+    session_id="session-1",
+    run_id="run-1",
+    actor=Actor(type="agent", id="researcher"),
+)
+
+await recorder.start_run(payload={"task": "summarize"})
+attempt = await recorder.before_model_call(
+    step_id="step-1",
+    payload={"model": "example-model", "messages": [{"role": "user", "content": "Hi"}]},
+)
+
+# The real model call starts only after model.requested is durably appended.
+response = await model.generate()
+await recorder.model_completed(attempt, payload={"message": response})
+```
+
+If the process stops after `before_model_call`, inspection reports an unresolved attempt. An adapter
+can then ask the provider for a result, require human confirmation, or retry with a new
+`attempt_id`; the generic library never silently repeats an external side effect.
+
+## Stores
+
+`EventStore` has three implementations:
+
+- `MemoryEventStore`: process-local reference implementation and test double.
+- `RedisEventStore`: atomic append through Lua, with per-session cluster key co-location.
+- `SqlEventStore`: one SQLAlchemy 2.x implementation for SQLite, MySQL, and PostgreSQL.
+
+Redis and SQL clients are supplied by the application so pool size, connection timeout, and
+deployment-specific durability are explicit. Install optional dependencies with
+`agent-ledger[redis]`, `agent-ledger[sql]`, `agent-ledger[mysql]`, or
+`agent-ledger[postgres]`.
+
+## Design boundaries
+
+- No collector or mandatory network service in v1.
+- No generic cross-framework `RunContext` serializer.
+- No automatic replay of an unresolved tool side effect.
+- No exactly-once claim. Appends are atomic and idempotent; external calls are not transactional
+  with the ledger.
+- No global ordering claim. `commit_cursor` orders one session's stored events for display and
+  pagination; causal links define execution relationships.
+
+See [RFC 0001](spec/rfcs/0001-agent-ledger.md) for the contract and
+[the plain-loop example](examples/plain_loop.py) for adapter-owned recovery.
+
+## Development
+
+```bash
+uv sync --all-extras
+make fix
+make lint
+make test
+```
+

examples/plain_loop.py

@@ -0,0 +1,47 @@
+import asyncio
+
+from agent_ledger import Actor, SessionRecorder
+from agent_ledger.frameworks.plain_loop import PlainLoopContext, PlainLoopProfile
+from agent_ledger.stores.memory import MemoryEventStore
+
+
+async def main() -> None:
+    store = MemoryEventStore()
+    actor = Actor(type="agent", id="example", framework="plain-loop")
+    recorder = SessionRecorder(
+        store=store,
+        session_id="session-1",
+        run_id="run-1",
+        actor=actor,
+    )
+    profile = PlainLoopProfile()
+
+    await recorder.start_run(payload={"messages": [{"role": "user", "content": "hello"}]})
+    await recorder.start_step("step-1")
+    attempt = await recorder.before_model_call(
+        "step-1",
+        payload={"model": "example-model"},
+    )
+    await recorder.model_completed(
+        attempt,
+        payload={"message": {"role": "assistant", "content": "Hello!"}},
+    )
+    await recorder.complete_step("step-1")
+    await profile.save(
+        recorder,
+        PlainLoopContext(
+            messages=[
+                {"role": "user", "content": "hello"},
+                {"role": "assistant", "content": "Hello!"},
+            ],
+            completed_steps=["step-1"],
+        ),
+    )
+
+    events = [event async for event in store.read_stream(recorder.stream)]
+    recovered = profile.recover(events)
+    print(recovered.context.model_dump())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-ledger"
+version = "0.1.0"
+description = "A framework-neutral event ledger for durable agent sessions"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Agent Ledger contributors" }]
+keywords = ["agent", "event-sourcing", "session", "trajectory", "recovery"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["pydantic>=2.10,<3"]
+
+[project.urls]
+Repository = "https://github.com/compforge/agent-ledger"
+Issues = "https://github.com/compforge/agent-ledger/issues"
+
+[project.optional-dependencies]
+redis = ["redis>=5,<7"]
+sql = ["SQLAlchemy[asyncio]>=2.0,<3", "aiosqlite>=0.20,<1"]
+mysql = ["SQLAlchemy[asyncio]>=2.0,<3", "asyncmy>=0.2,<1"]
+postgres = ["SQLAlchemy[asyncio]>=2.0,<3", "asyncpg>=0.30,<1"]
+all = [
+  "redis>=5,<7",
+  "SQLAlchemy[asyncio]>=2.0,<3",
+  "aiosqlite>=0.20,<1",
+  "asyncmy>=0.2,<1",
+  "asyncpg>=0.30,<1",
+]
+
+[dependency-groups]
+dev = [
+  "jsonschema>=4.23,<5",
+  "mypy>=1.15,<2",
+  "pytest>=8.3,<9",
+  "pytest-asyncio>=0.25,<1",
+  "ruff>=0.11,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_ledger"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["agent_ledger"]