functualize-state-sqlite 0.1.0__py3-none-any.whl

functualize_state_sqlite/state_store.py

@@ -0,0 +1,178 @@
+"""SQLite-backed state store implementing StateStoreProtocol.
+
+Provides persistent key-value state storage per job namespace, backed by
+the SQLiteBackend's state table. Values are JSON-serialized for storage;
+non-serializable values are replaced with a type-indicating placeholder.
+
+Each SQLiteStateStore instance is scoped to a specific scope_id and
+job_namespace, providing namespace isolation per job.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from functualize_state_sqlite.sqlite_backend import SQLiteBackend
+
+__all__ = ["SQLiteStateStore"]
+
+logger = logging.getLogger(__name__)
+
+_NON_SERIALIZABLE_TEMPLATE = "<non-serializable: {type_name}>"
+
+
+def _serialize_value(value: Any) -> str:
+    """Serialize a value to JSON string.
+
+    If the value cannot be serialized, returns a JSON-encoded placeholder
+    string containing the type name (Requirement 23.10).
+
+    Args:
+        value: Any Python value to serialize.
+
+    Returns:
+        A JSON string representation of the value.
+    """
+    try:
+        return json.dumps(value)
+    except (TypeError, ValueError, OverflowError):
+        type_name = type(value).__name__
+        placeholder = _NON_SERIALIZABLE_TEMPLATE.format(type_name=type_name)
+        return json.dumps(placeholder)
+
+
+def _deserialize_value(value_json: str) -> Any:
+    """Deserialize a JSON string back to a Python value.
+
+    Args:
+        value_json: JSON string to deserialize.
+
+    Returns:
+        The deserialized Python value.
+    """
+    return json.loads(value_json)
+
+
+class SQLiteStateStore:
+    """StateStoreProtocol implementation backed by SQLite.
+
+    Each instance is scoped to a specific (scope_id, job_namespace) pair,
+    providing namespace isolation between jobs. All values are persisted
+    immediately to the database on write.
+
+    Args:
+        backend: The SQLiteBackend instance managing the database connection.
+        scope_id: The workflow scope identifier for state isolation.
+        job_namespace: The job namespace (typically the job name) for this store.
+    """
+
+    def __init__(
+        self,
+        backend: SQLiteBackend,
+        scope_id: str,
+        job_namespace: str,
+    ) -> None:
+        self._backend = backend
+        self._scope_id = scope_id
+        self._job_namespace = job_namespace
+
+    @property
+    def scope_id(self) -> str:
+        """The workflow scope identifier."""
+        return self._scope_id
+
+    @property
+    def job_namespace(self) -> str:
+        """The job namespace for this store instance."""
+        return self._job_namespace
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a value by key from the current job's namespace.
+
+        Args:
+            key: The state key to look up.
+            default: Value to return if key not found.
+
+        Returns:
+            The deserialized value, or default if not found.
+        """
+        value_json = self._backend.get_state(self._scope_id, self._job_namespace, key)
+        if value_json is None:
+            return default
+        return _deserialize_value(value_json)
+
+    def set(self, key: str, value: Any) -> None:
+        """Store a value under the given key in the current job's namespace.
+
+        The value is immediately persisted to the database as JSON.
+        Non-serializable values are stored as a placeholder string
+        containing the type name.
+
+        Args:
+            key: The state key.
+            value: The value to store (will be JSON-serialized).
+        """
+        value_json = _serialize_value(value)
+        self._backend.upsert_state(self._scope_id, self._job_namespace, key, value_json)
+
+    def delete(self, key: str) -> None:
+        """Remove a key from the current job's namespace.
+
+        No-op if the key doesn't exist.
+
+        Args:
+            key: The state key to delete.
+        """
+        self._backend.delete_state(self._scope_id, self._job_namespace, key)
+
+    def keys(self) -> list[str]:
+        """Return all stored key names in the current job's namespace.
+
+        Returns:
+            List of key strings.
+        """
+        return self._backend.get_namespace_keys(self._scope_id, self._job_namespace)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a copy of all state as a plain dict for the current namespace.
+
+        Returns:
+            Dict mapping keys to their deserialized values.
+        """
+        raw = self._backend.get_namespace_state(self._scope_id, self._job_namespace)
+        return {key: _deserialize_value(value_json) for key, value_json in raw.items()}
+
+    def clear(self) -> None:
+        """Remove all stored state in the current job's namespace."""
+        self._backend.clear_namespace_state(self._scope_id, self._job_namespace)
+
+    def get_job_state(self, job_name: str, key: str, default: Any = None) -> Any:
+        """Read a value from another job's namespace.
+
+        Provides cross-job state access for coordination between jobs
+        within the same workflow scope.
+
+        Args:
+            job_name: The job namespace to read from.
+            key: The state key within that namespace.
+            default: Value to return if key not found.
+
+        Returns:
+            The deserialized value from the specified job's namespace,
+            or default if not found.
+        """
+        value_json = self._backend.get_state(self._scope_id, job_name, key)
+        if value_json is None:
+            return default
+        return _deserialize_value(value_json)
+
+    def list_job_namespaces(self) -> list[str]:
+        """Return all job namespaces that have stored state in this scope.
+
+        Returns:
+            List of job namespace strings.
+        """
+        return self._backend.list_namespaces(self._scope_id)

functualize_state_sqlite/tracker.py

@@ -0,0 +1,318 @@
+"""Execution tracker for session management, execution recording, and AI context.
+
+Provides high-level operations for tracking job executions within sessions,
+including automatic session resume based on TTL, nested execution linkage,
+and a plain-text AI context summary.
+
+The tracker delegates all database operations to the SQLiteBackend and
+follows the error resilience pattern (Requirement 23.11): database failures
+are logged but never propagate to callers.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from functualize_state_sqlite.sqlite_backend import SQLiteBackend
+
+__all__ = ["ExecutionTracker"]
+
+logger = logging.getLogger(__name__)
+
+# Default session TTL: 30 minutes (in seconds)
+_DEFAULT_SESSION_TTL_SECONDS = 30 * 60
+
+
+class ExecutionTracker:
+    """Tracks job executions within sessions, providing history and AI context.
+
+    The tracker manages session lifecycle (auto-resume or create new) and
+    records execution start/end events. It supports nested executions via
+    parent_uid linkage and provides a plain-text summary for AI assistants.
+
+    Args:
+        backend: An initialized SQLiteBackend instance.
+        session_ttl: Time in seconds before a session is considered expired.
+            Defaults to 1800 (30 minutes).
+        scope_id: The workflow scope identifier. Defaults to "default".
+    """
+
+    def __init__(
+        self,
+        backend: SQLiteBackend,
+        *,
+        session_ttl: float = _DEFAULT_SESSION_TTL_SECONDS,
+        scope_id: str = "default",
+    ) -> None:
+        self._backend = backend
+        self._session_ttl = session_ttl
+        self._scope_id = scope_id
+        self._session_id: str | None = None
+        self._execution_count: int = 0
+
+    @property
+    def session_id(self) -> str | None:
+        """The current active session ID, or None if no session is active."""
+        return self._session_id
+
+    @property
+    def session_ttl(self) -> float:
+        """The session TTL in seconds."""
+        return self._session_ttl
+
+    # ─── Session Management ───────────────────────────────────────────
+
+    def ensure_session(self) -> str:
+        """Ensure an active session exists, resuming or creating as needed.
+
+        If the latest session's updated_at is within the TTL, resume it.
+        Otherwise, create a new session.
+
+        Returns:
+            The active session ID.
+        """
+        if self._session_id is not None:
+            return self._session_id
+
+        # Try to resume the latest session
+        latest = self._backend.get_latest_session()
+        if latest is not None:
+            updated_at = latest.get("updated_at", 0.0)
+            elapsed = time.time() - updated_at
+            if elapsed < self._session_ttl:
+                self._session_id = latest["session_id"]
+                # Touch the session to keep it alive
+                self._backend.update_session(self._session_id)
+                logger.debug(
+                    "Resumed session %s (idle %.1fs)",
+                    self._session_id,
+                    elapsed,
+                )
+                return self._session_id
+
+        # Create a new session
+        self._session_id = str(uuid.uuid4())
+        success = self._backend.insert_session(
+            self._session_id,
+            self._scope_id,
+        )
+        if success:
+            logger.debug("Created new session %s", self._session_id)
+        else:
+            logger.error("Failed to create session %s", self._session_id)
+
+        return self._session_id
+
+    # ─── Execution Recording ──────────────────────────────────────────
+
+    def record_start(
+        self,
+        job_name: str,
+        *,
+        kwargs_json: str | None = None,
+        parent_uid: str | None = None,
+        depth: int = 0,
+    ) -> str:
+        """Record the start of a job execution.
+
+        Ensures a session is active, generates a unique execution UID,
+        and inserts the execution record.
+
+        Args:
+            job_name: The name of the job being executed.
+            kwargs_json: JSON-serialized kwargs passed to the job.
+            parent_uid: The execution UID of the parent (for nested calls).
+            depth: The nesting depth (0 for top-level).
+
+        Returns:
+            The generated execution UID.
+        """
+        session_id = self.ensure_session()
+        execution_uid = str(uuid.uuid4())
+
+        success = self._backend.insert_execution(
+            execution_uid,
+            session_id,
+            job_name,
+            kwargs_json=kwargs_json,
+            parent_uid=parent_uid,
+            depth=depth,
+        )
+
+        if success:
+            self._execution_count += 1
+            # Keep session alive
+            self._backend.update_session(session_id)
+            logger.debug(
+                "Recorded execution start: %s (job=%s, parent=%s)",
+                execution_uid,
+                job_name,
+                parent_uid,
+            )
+        else:
+            logger.error(
+                "Failed to record execution start for job %s",
+                job_name,
+            )
+
+        return execution_uid
+
+    def record_end(
+        self,
+        execution_uid: str,
+        *,
+        status: str,
+        duration_ms: float,
+        result_json: str | None = None,
+        error_message: str | None = None,
+        error_type: str | None = None,
+    ) -> None:
+        """Record the end of a job execution.
+
+        Updates the execution record with completion details.
+
+        Args:
+            execution_uid: The execution UID returned by record_start().
+            status: The final status ("success" or "failure").
+            duration_ms: The execution duration in milliseconds.
+            result_json: JSON-serialized return value (if serializable).
+            error_message: Error message (for failed executions).
+            error_type: Error type name (for failed executions).
+        """
+        success = self._backend.update_execution(
+            execution_uid,
+            status=status,
+            duration_ms=duration_ms,
+            result_json=result_json,
+            error_message=error_message,
+            error_type=error_type,
+        )
+
+        if success:
+            # Keep session alive
+            if self._session_id:
+                self._backend.update_session(self._session_id)
+            logger.debug(
+                "Recorded execution end: %s (status=%s, duration=%.1fms)",
+                execution_uid,
+                status,
+                duration_ms,
+            )
+        else:
+            logger.error(
+                "Failed to record execution end for %s",
+                execution_uid,
+            )
+
+    # ─── Query Methods ────────────────────────────────────────────────
+
+    def get_execution_history(
+        self,
+        *,
+        limit: int = 20,
+    ) -> list[dict[str, Any]]:
+        """Get recent executions for the current session.
+
+        Args:
+            limit: Maximum number of executions to return.
+
+        Returns:
+            List of execution records as dicts, ordered by start time descending.
+        """
+        if self._session_id is None:
+            return []
+        return self._backend.get_session_executions(
+            self._session_id,
+            limit=limit,
+        )
+
+    def get_session_execution_count(self) -> int:
+        """Get the total number of executions in the current session.
+
+        Returns:
+            The count of executions, or 0 if no session is active.
+        """
+        if self._session_id is None:
+            return 0
+
+        row = self._backend.fetch_one(
+            "SELECT COUNT(*) as count FROM executions WHERE session_id = ?",
+            (self._session_id,),
+        )
+        if row is not None:
+            return int(row["count"])
+        return 0
+
+    # ─── AI Context ───────────────────────────────────────────────────
+
+    def to_ai_context(self) -> str:
+        """Generate a plain-text summary for AI assistant consumption.
+
+        Returns a formatted summary containing:
+        - Session ID
+        - Total execution count in the session
+        - List of recent 20 executions with job name, status, duration, timestamp
+
+        Returns:
+            A plain-text string suitable for including in AI context.
+        """
+        if self._session_id is None:
+            return "No active execution session."
+
+        total_count = self.get_session_execution_count()
+        recent = self._backend.get_session_executions(
+            self._session_id,
+            limit=20,
+        )
+
+        lines: list[str] = [
+            "## Execution Context",
+            f"Session: {self._session_id}",
+            f"Total executions: {total_count}",
+            "",
+        ]
+
+        if not recent:
+            lines.append("No executions recorded yet.")
+        else:
+            lines.append("Recent executions (most recent first):")
+            lines.append("")
+            for exec_record in recent:
+                job_name = exec_record.get("job_name", "unknown")
+                status = exec_record.get("status", "unknown")
+                duration = exec_record.get("duration_ms")
+                started_at = exec_record.get("started_at")
+                parent_uid = exec_record.get("parent_uid")
+
+                # Format timestamp
+                ts_str = ""
+                if started_at is not None:
+                    dt = datetime.fromtimestamp(started_at, tz=UTC)
+                    ts_str = dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+                # Format duration
+                dur_str = ""
+                if duration is not None:
+                    if duration < 1000:
+                        dur_str = f"{duration:.0f}ms"
+                    else:
+                        dur_str = f"{duration / 1000:.1f}s"
+
+                # Build the line
+                parts = [f"  - {job_name}"]
+                parts.append(f"[{status}]")
+                if dur_str:
+                    parts.append(f"({dur_str})")
+                if ts_str:
+                    parts.append(f"at {ts_str}")
+                if parent_uid:
+                    parts.append("(nested)")
+
+                lines.append(" ".join(parts))
+
+        return "\n".join(lines)

functualize_state_sqlite-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+functualize_state_sqlite/__init__.py,sha256=JvtetjkGWcYOUvqgdEOy1Z8fQOvSKttdwXqq6kUtEvI,487
+functualize_state_sqlite/_backend.py,sha256=U_AKJ-ZD-PyF1z-8o8aplSduXYS0VoUF32q_Z8jOW8Y,5031
+functualize_state_sqlite/_execution_store.py,sha256=7ndSMD6bGAq_W1QpQo3NRsukl3NVGNHTe-bgUBXhY_Q,12360
+functualize_state_sqlite/_migrations.py,sha256=dyZ8ghoMeDKdD_ea96mOCJGAXfWsVxM9KA628V_AsRk,4819
+functualize_state_sqlite/_plugin.py,sha256=SDbbBNahw0tZ52jDWqdD5bCx1hdDHIB4gb2B1Tp0IJg,8272
+functualize_state_sqlite/plugin.py,sha256=e2H5SE1fSI-2sNlKJc70hhA1nReVHTrtoMwj-8gr7sM,12960
+functualize_state_sqlite/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+functualize_state_sqlite/sqlite_backend.py,sha256=URKoE8U8H3uV3-uD4kwXn0K9kiev1bDYMV2NR6QehTc,22535
+functualize_state_sqlite/state_store.py,sha256=NvtVkhKHOSwIgbsKG9PWXlqfU1SAb6NTGhVE2HanD5g,5804
+functualize_state_sqlite/tracker.py,sha256=qntfLgfBO5PvEuN-CG34bUEFzWkMHQh4T3OHtNakGeQ,10712
+functualize_state_sqlite-0.1.0.dist-info/METADATA,sha256=FvNa5SXkVTqpIaPQYvR0zMgMESKUqIJ1yuq77NyUIok,4330
+functualize_state_sqlite-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+functualize_state_sqlite-0.1.0.dist-info/entry_points.txt,sha256=hSbeMehidZ8rCyB11aj_ZsE7s6-L9TcEhRHYzKO0Bm0,82
+functualize_state_sqlite-0.1.0.dist-info/RECORD,,

functualize_state_sqlite-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

functualize_state_sqlite-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[functualize.state_providers]
+sqlite = functualize_state_sqlite:SQLiteStatePlugin