functualize-state-sqlite 0.1.0__tar.gz

functualize_state_sqlite-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_state_sqlite-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: functualize-state-sqlite
+Version: 0.1.0
+Summary: SQLite-backed state persistence and execution tracking plugin for functualize
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: functualize-state<1.0.0,>=0.1.0
+Requires-Dist: functualize<1.0.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.82.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-state-sqlite
+
+> **Status: Published** — Independently installable from PyPI.
+
+SQLite-backed state persistence and execution tracking plugin for functualize. Implements the `StateBackend` and `ExecutionStore` protocols from `functualize-state`, providing durable key-value storage and full execution history using a local SQLite database in WAL mode. Zero external dependencies beyond the Python standard library's `sqlite3` module.
+
+## Installation
+
+```bash
+pip install functualize-state-sqlite
+```
+
+## Quick Start
+
+```python
+from functualize_state_sqlite import SQLiteStateBackend
+
+# Use as a context manager for automatic cleanup
+with SQLiteStateBackend(db_path="my_app.db") as backend:
+    backend.set("deploy_count", 42)
+    backend.set("last_env", "staging")
+
+    count = backend.get("deploy_count")
+    print(f"Deployments: {count}")
+
+    keys = backend.keys(prefix="deploy")
+    print(f"Keys: {keys}")
+```
+
+## Features
+
+- **Persistent key-value state** — JSON-encoded values stored in SQLite with automatic schema initialization
+- **WAL mode for concurrency** — concurrent read access without blocking writes, suitable for multi-process environments
+- **Execution tracking** — full session and execution history with nested invocation support and phase recording
+- **Namespace-scoped state** — `SQLiteStateStore` provides per-job namespace isolation within workflow scopes
+- **Context manager support** — all backends support `with` statements for automatic connection cleanup
+- **Zero external dependencies** — uses only Python's built-in `sqlite3` module
+- **Automatic schema migrations** — database schema is created and migrated transparently on first access
+
+## API Reference
+
+Public classes exported by this plugin:
+
+- `SQLiteStateBackend` — Implements the `StateBackend` protocol with `get()`, `set()`, `delete()`, and `keys()` methods for persistent key-value storage using a dedicated `kv_state` table.
+- `SQLiteExecutionStore` — Implements the `ExecutionStore` protocol for recording and querying execution records and phase tracking. Methods include `insert_execution()`, `update_execution()`, `get_session_executions()`, `insert_phase()`, and `get_execution_phases()`.
+- `SQLiteStatePlugin` — Plugin that registers `SQLiteStateBackend` and `SQLiteExecutionStore` with the DI registry at boot time. Hooks into `APP_READY` and `ON_SCOPE_CREATED` lifecycle events.
+- `ExecutionStatePlugin` — Full lifecycle plugin that tracks job executions automatically. Hooks into `BEFORE_JOB`, `AFTER_SUCCESS`, `AFTER_FAILURE`, `INVOKE_START`, `INVOKE_END`, and `ON_SCOPE_CREATED` for comprehensive execution history.
+
+Internal classes (available via direct import but not part of the public protocol surface):
+
+- `SQLiteBackend` — Low-level connection manager with WAL mode, schema initialization, and query helpers for sessions, executions, steps, and namespaced state.
+- `SQLiteStateStore` — `StateStoreProtocol` implementation scoped to a `(scope_id, job_namespace)` pair, with `get()`, `set()`, `delete()`, `keys()`, `to_dict()`, `clear()`, and cross-job access via `get_job_state()`.
+- `ExecutionTracker` — High-level session management and execution recording with automatic session resume based on TTL, and AI context summary generation via `to_ai_context()`.
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-state-sqlite/tests/ -v
+```
+
+Build the package:
+
+```bash
+uv build --package functualize-state-sqlite
+```

functualize_state_sqlite-0.1.0/README.md

@@ -0,0 +1,67 @@
+# functualize-state-sqlite
+
+> **Status: Published** — Independently installable from PyPI.
+
+SQLite-backed state persistence and execution tracking plugin for functualize. Implements the `StateBackend` and `ExecutionStore` protocols from `functualize-state`, providing durable key-value storage and full execution history using a local SQLite database in WAL mode. Zero external dependencies beyond the Python standard library's `sqlite3` module.
+
+## Installation
+
+```bash
+pip install functualize-state-sqlite
+```
+
+## Quick Start
+
+```python
+from functualize_state_sqlite import SQLiteStateBackend
+
+# Use as a context manager for automatic cleanup
+with SQLiteStateBackend(db_path="my_app.db") as backend:
+    backend.set("deploy_count", 42)
+    backend.set("last_env", "staging")
+
+    count = backend.get("deploy_count")
+    print(f"Deployments: {count}")
+
+    keys = backend.keys(prefix="deploy")
+    print(f"Keys: {keys}")
+```
+
+## Features
+
+- **Persistent key-value state** — JSON-encoded values stored in SQLite with automatic schema initialization
+- **WAL mode for concurrency** — concurrent read access without blocking writes, suitable for multi-process environments
+- **Execution tracking** — full session and execution history with nested invocation support and phase recording
+- **Namespace-scoped state** — `SQLiteStateStore` provides per-job namespace isolation within workflow scopes
+- **Context manager support** — all backends support `with` statements for automatic connection cleanup
+- **Zero external dependencies** — uses only Python's built-in `sqlite3` module
+- **Automatic schema migrations** — database schema is created and migrated transparently on first access
+
+## API Reference
+
+Public classes exported by this plugin:
+
+- `SQLiteStateBackend` — Implements the `StateBackend` protocol with `get()`, `set()`, `delete()`, and `keys()` methods for persistent key-value storage using a dedicated `kv_state` table.
+- `SQLiteExecutionStore` — Implements the `ExecutionStore` protocol for recording and querying execution records and phase tracking. Methods include `insert_execution()`, `update_execution()`, `get_session_executions()`, `insert_phase()`, and `get_execution_phases()`.
+- `SQLiteStatePlugin` — Plugin that registers `SQLiteStateBackend` and `SQLiteExecutionStore` with the DI registry at boot time. Hooks into `APP_READY` and `ON_SCOPE_CREATED` lifecycle events.
+- `ExecutionStatePlugin` — Full lifecycle plugin that tracks job executions automatically. Hooks into `BEFORE_JOB`, `AFTER_SUCCESS`, `AFTER_FAILURE`, `INVOKE_START`, `INVOKE_END`, and `ON_SCOPE_CREATED` for comprehensive execution history.
+
+Internal classes (available via direct import but not part of the public protocol surface):
+
+- `SQLiteBackend` — Low-level connection manager with WAL mode, schema initialization, and query helpers for sessions, executions, steps, and namespaced state.
+- `SQLiteStateStore` — `StateStoreProtocol` implementation scoped to a `(scope_id, job_namespace)` pair, with `get()`, `set()`, `delete()`, `keys()`, `to_dict()`, `clear()`, and cross-job access via `get_job_state()`.
+- `ExecutionTracker` — High-level session management and execution recording with automatic session resume based on TTL, and AI context summary generation via `to_ai_context()`.
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-state-sqlite/tests/ -v
+```
+
+Build the package:
+
+```bash
+uv build --package functualize-state-sqlite
+```

functualize_state_sqlite-0.1.0/examples/README.md

@@ -0,0 +1,11 @@
+# functualize-state-sqlite Examples
+
+Durable SQLite-backed state (WAL mode, stdlib-only).
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`persistent_counter/`](persistent_counter/) | `SQLiteStateBackend` as a `StateBackend`: values survive across processes; keys listing by prefix |
+
+```bash
+uv run pytest plugins/functualize-state-sqlite/examples/ -v
+```

functualize_state_sqlite-0.1.0/examples/persistent_counter/persistent_counter.py

@@ -0,0 +1,25 @@
+"""Durable state: a run counter that survives process restarts.
+
+Run twice and watch the count keep climbing:
+    func persistent_counter.py bump
+    func persistent_counter.py bump
+"""
+
+from pathlib import Path
+
+from functualize_state_sqlite import SQLiteStateBackend
+
+from functualize.job import RunContext
+
+DB_PATH = Path(__file__).parent / "counter.db"
+
+
+def bump(rc: RunContext) -> int:
+    """Increment a counter stored durably in SQLite."""
+    with SQLiteStateBackend(db_path=str(DB_PATH)) as backend:
+        count = backend.get("runs", 0) + 1
+        backend.set("runs", count)
+        backend.set("last_run_note", f"run #{count}")
+        rc.log(f"Persistent run count: {count}")
+        rc.log(f"Keys stored: {backend.keys()}")
+    return count

functualize_state_sqlite-0.1.0/examples/persistent_counter/test_persistent_counter.py

@@ -0,0 +1,23 @@
+"""Tests for the persistent counter example."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+import persistent_counter
+from functualize_state_sqlite import SQLiteStateBackend
+
+
+def test_counter_persists_across_backend_instances(tmp_path, monkeypatch):
+    db = tmp_path / "counter.db"
+    monkeypatch.setattr(persistent_counter, "DB_PATH", db)
+
+    rc = MagicMock()
+    assert persistent_counter.bump(rc) == 1
+    # New backend instance (fresh "process") still sees the stored value
+    assert persistent_counter.bump(rc) == 2
+
+    with SQLiteStateBackend(db_path=str(db)) as backend:
+        assert backend.get("runs") == 2

functualize_state_sqlite-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "functualize-state-sqlite"
+version = "0.1.0"
+description = "SQLite-backed state persistence and execution tracking plugin for functualize"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "functualize>=0.1.0,<1.0.0",
+    "functualize-state>=0.1.0,<1.0.0",
+]
+
+[project.entry-points."functualize.state_providers"]
+sqlite = "functualize_state_sqlite:SQLiteStatePlugin"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "hypothesis>=6.82.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+functualize = { workspace = true }
+functualize-state = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_state_sqlite"]

functualize_state_sqlite-0.1.0/src/functualize_state_sqlite/__init__.py

@@ -0,0 +1,13 @@
+"""Functualize State SQLite Plugin - SQLite-backed state persistence and execution tracking."""
+
+from functualize_state_sqlite._backend import SQLiteStateBackend
+from functualize_state_sqlite._execution_store import SQLiteExecutionStore
+from functualize_state_sqlite._plugin import SQLiteStatePlugin
+from functualize_state_sqlite.plugin import ExecutionStatePlugin
+
+__all__ = [
+    "ExecutionStatePlugin",
+    "SQLiteExecutionStore",
+    "SQLiteStateBackend",
+    "SQLiteStatePlugin",
+]

functualize_state_sqlite-0.1.0/src/functualize_state_sqlite/_backend.py

@@ -0,0 +1,160 @@
+"""SQLite StateBackend implementation.
+
+Implements the StateBackend protocol from functualize-state using SQLite
+in WAL mode for concurrent access. Values are JSON-encoded for storage.
+Uses only stdlib sqlite3 (zero external dependencies).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+__all__ = ["SQLiteStateBackend"]
+
+logger = logging.getLogger(__name__)
+
+_STATE_SCHEMA_SQL = """\
+CREATE TABLE IF NOT EXISTS kv_state (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at REAL NOT NULL
+);
+"""
+
+
+class SQLiteStateBackend:
+    """StateBackend protocol implementation backed by SQLite.
+
+    Provides persistent key-value state storage with JSON-encoded values.
+    Uses WAL mode for concurrent read access without blocking writes.
+
+    Args:
+        db_path: Path to the SQLite database file. If None, defaults to
+            `.functualize/state.db` relative to the current working directory.
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        if db_path is None:
+            self._db_path = Path.cwd() / ".functualize" / "state.db"
+        else:
+            self._db_path = Path(db_path)
+
+        self._conn: sqlite3.Connection | None = None
+        self._initialized = False
+
+    @property
+    def db_path(self) -> Path:
+        """The resolved path to the database file."""
+        return self._db_path
+
+    def _ensure_initialized(self) -> sqlite3.Connection:
+        """Ensure the database is initialized and return the connection."""
+        if self._conn is not None and self._initialized:
+            return self._conn
+
+        # Ensure the directory exists
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open connection
+        self._conn = sqlite3.connect(
+            str(self._db_path),
+            timeout=10.0,
+            check_same_thread=False,
+        )
+
+        # Enable WAL mode for concurrent access
+        self._conn.execute("PRAGMA journal_mode = WAL")
+        self._conn.execute("PRAGMA synchronous = NORMAL")
+        self._conn.commit()
+
+        # Create schema
+        self._conn.executescript(_STATE_SCHEMA_SQL)
+        self._conn.commit()
+
+        self._initialized = True
+        logger.debug("SQLiteStateBackend initialized at %s", self._db_path)
+        return self._conn
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value by key, returning default if not found.
+
+        The stored JSON value is deserialized back to a Python object.
+        """
+        conn = self._ensure_initialized()
+        cursor = conn.execute(
+            "SELECT value FROM kv_state WHERE key = ?",
+            (key,),
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return default
+        return json.loads(row[0])
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value for a key.
+
+        The value is JSON-encoded before storage.
+        """
+        conn = self._ensure_initialized()
+        value_json = json.dumps(value)
+        now = time.time()
+        conn.execute(
+            "INSERT OR REPLACE INTO kv_state (key, value, updated_at) VALUES (?, ?, ?)",
+            (key, value_json, now),
+        )
+        conn.commit()
+
+    def delete(self, key: str) -> None:
+        """Delete a key from the state backend.
+
+        No-op if the key does not exist.
+        """
+        conn = self._ensure_initialized()
+        conn.execute("DELETE FROM kv_state WHERE key = ?", (key,))
+        conn.commit()
+
+    def keys(self, prefix: str = "") -> list[str]:
+        """Return all keys, optionally filtered by prefix."""
+        conn = self._ensure_initialized()
+        if prefix:
+            cursor = conn.execute(
+                "SELECT key FROM kv_state WHERE key LIKE ? ESCAPE '\\'",
+                (self._escape_like(prefix) + "%",),
+            )
+        else:
+            cursor = conn.execute("SELECT key FROM kv_state")
+        return [row[0] for row in cursor.fetchall()]
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            except sqlite3.Error as e:
+                logger.warning("Error closing SQLiteStateBackend connection: %s", e)
+            finally:
+                self._conn = None
+                self._initialized = False
+
+    @staticmethod
+    def _escape_like(value: str) -> str:
+        """Escape special characters in a LIKE pattern."""
+        return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+    def __enter__(self) -> SQLiteStateBackend:
+        """Context manager entry — initialize if needed."""
+        self._ensure_initialized()
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        """Context manager exit — close connection."""
+        self.close()
+
+    def __del__(self) -> None:
+        """Ensure connection is closed on garbage collection."""
+        self.close()