runspool 0.1.0__py3-none-any.whl

runspool/__init__.py

@@ -0,0 +1,14 @@
+"""Runspool: a local-first CLI workflow engine for reliable personal automation.
+
+Runspool turns local scripts, files, and manual checklists into resumable,
+observable workflows backed by SQLite. Tasks move through an ordered list of
+steps; every transition is recorded, every step run is timed, and the whole
+lifecycle (pause, resume, retry, terminate) is controllable from the CLI and
+readable as JSON for scripts and AI agents.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

runspool/app.py

@@ -0,0 +1,85 @@
+"""Application context: assembles config and persistence for the CLI and daemon."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from runspool.config import AppConfig
+from runspool.persistence.connection import Database
+from runspool.persistence.event_log import EventLog
+from runspool.persistence.repository import TaskRepository
+from runspool.persistence.state_machine import StateMachine
+from runspool.persistence.step_run_log import StepRunLog
+
+DEFAULT_CONFIG_FILENAME = "config.yaml"
+
+
+@dataclass
+class AppContext:
+    config: AppConfig
+    db: Database
+    repo: TaskRepository
+    log: EventLog
+    step_runs: StepRunLog
+
+    def state_machine(self, workflow_name: str) -> StateMachine:
+        return StateMachine(self.repo, self.log, workflow=self.config.workflow(workflow_name))
+
+
+def load_context(config_path: Path | str) -> AppContext:
+    config = AppConfig.load(Path(config_path))
+    db = Database(config.database_path)
+    db.init()
+    return AppContext(
+        config=config,
+        db=db,
+        repo=TaskRepository(db),
+        log=EventLog(db),
+        step_runs=StepRunLog(db),
+    )
+
+
+def config_template(workspace_root: Path | str) -> str:
+    return f"""# Runspool configuration
+# Local-first: all state lives under workspace_root. Nothing is sent anywhere.
+workspace_root: {workspace_root}
+
+scheduler:
+  poll_interval_seconds: 5   # how often the daemon looks for work
+  max_retries: 3             # default retry budget per task
+  retry_delay_seconds: 0     # 0 = retry immediately; >0 = backoff (driven by the daemon)
+
+worker_pool:
+  size: 4                    # concurrent step executions
+  heartbeat_timeout_seconds: 1800
+
+# Per-step concurrency quota (defaults to 1). Raise it for cheap, parallelizable
+# steps; keep it at 1 for steps that must not overlap.
+concurrency: {{}}
+
+# Workflows are ordered lists of step names. The built-in steps below need no
+# network, API keys, or external tools.
+workflows:
+  local_file:
+    steps: [ingest_file, classify_text, normalize_markdown, summarize_text, archive]
+
+# Load custom steps from your own code. See docs/writing-steps.md.
+# plugin_paths: [steps]            # directories added to sys.path (relative to this file)
+# steps:
+#   my_custom_step:
+#     import: "my_module:MyCustomStep"
+"""
+
+
+def init_app(config_path: Path | str, *, workspace_root: Path | str) -> bool:
+    """Generate config (without overwriting an existing one) and initialise the
+    database. Returns whether a new config file was created."""
+    config_path = Path(config_path)
+    created = False
+    if not config_path.exists():
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(config_template(workspace_root), encoding="utf-8")
+        created = True
+    load_context(config_path)  # initialises the database
+    return created

runspool/builtin_steps/__init__.py

@@ -0,0 +1,41 @@
+"""Built-in steps: a small, dependency-free local-file pipeline.
+
+These steps require no network, API keys, or external binaries. They exist to
+make Runspool runnable the moment it is installed and to serve as readable
+reference implementations of the step contract:
+
+    ingest_file -> classify_text -> normalize_markdown -> summarize_text -> archive
+"""
+
+from __future__ import annotations
+
+from runspool.builtin_steps.archive import ArchiveStep
+from runspool.builtin_steps.file_intake import FileIntakeStep
+from runspool.builtin_steps.markdown_normalize import MarkdownNormalizeStep
+from runspool.builtin_steps.text_classify import TextClassifyStep
+from runspool.builtin_steps.text_summarize import TextSummarizeStep
+from runspool.engine.registry import StepRegistry
+
+BUILTIN_STEP_CLASSES = (
+    FileIntakeStep,
+    TextClassifyStep,
+    MarkdownNormalizeStep,
+    TextSummarizeStep,
+    ArchiveStep,
+)
+
+__all__ = [
+    "FileIntakeStep",
+    "TextClassifyStep",
+    "MarkdownNormalizeStep",
+    "TextSummarizeStep",
+    "ArchiveStep",
+    "BUILTIN_STEP_CLASSES",
+    "register_builtins",
+]
+
+
+def register_builtins(registry: StepRegistry) -> None:
+    """Register every built-in step into ``registry``."""
+    for cls in BUILTIN_STEP_CLASSES:
+        registry.register(cls())

runspool/builtin_steps/archive.py

@@ -0,0 +1,25 @@
+"""archive: move the task workspace into the ``ready/`` directory.
+
+This bounds the local automation: once a task is archived, its artifacts live in
+a stable, predictable location and the active workspace is freed.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+from runspool.builtin_steps.workspace import archive_dir, task_workspace
+from runspool.engine.step import Step, StepContext, StepResult
+
+
+class ArchiveStep(Step):
+    name = "archive"
+
+    def run(self, ctx: StepContext) -> StepResult:
+        ws = task_workspace(ctx.config, ctx.task)
+        ready = archive_dir(ctx.config, ctx.task)
+        ready.parent.mkdir(parents=True, exist_ok=True)
+        if ready.exists():
+            shutil.rmtree(ready)
+        shutil.move(str(ws), str(ready))
+        return StepResult(message=f"archived to {ready}")

runspool/builtin_steps/file_intake.py

@@ -0,0 +1,46 @@
+"""ingest_file: read the task input file into the workspace and record metadata."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from runspool.builtin_steps.workspace import task_workspace
+from runspool.engine.step import Step, StepContext, StepResult
+
+
+class FileIntakeStep(Step):
+    name = "ingest_file"
+
+    def run(self, ctx: StepContext) -> StepResult:
+        src = Path(ctx.task["input"]).expanduser()
+        if not src.exists():
+            raise FileNotFoundError(f"input file not found: {src}")
+        if not src.is_file():
+            raise ValueError(f"input is not a file: {src}")
+
+        ctx.heartbeat("reading input")
+        text = src.read_text(encoding="utf-8", errors="replace")
+        ws = task_workspace(ctx.config, ctx.task)
+        (ws / "source.txt").write_text(text, encoding="utf-8")
+
+        metadata = {
+            "original_path": str(src),
+            "original_name": src.name,
+            "suffix": src.suffix,
+            "size_bytes": src.stat().st_size,
+            "line_count": text.count("\n") + (1 if text and not text.endswith("\n") else 0),
+            "word_count": len(text.split()),
+            "char_count": len(text),
+        }
+        (ws / "metadata.json").write_text(
+            json.dumps(metadata, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+
+        # Give the task a readable name if it does not have one yet.
+        updates = {}
+        if not ctx.task.get("name"):
+            updates["name"] = src.stem
+        return StepResult(
+            message=f"ingested {src.name} ({metadata['word_count']} words)", updates=updates
+        )

runspool/builtin_steps/markdown_normalize.py

@@ -0,0 +1,35 @@
+"""normalize_markdown: tidy the source text into clean Markdown."""
+
+from __future__ import annotations
+
+import re
+
+from runspool.builtin_steps.workspace import read_source, task_workspace
+from runspool.engine.step import Step, StepContext, StepResult
+
+_BLANK_RUN = re.compile(r"\n{3,}")
+
+
+def normalize(text: str, *, title: str | None = None) -> str:
+    # Strip trailing whitespace from every line.
+    lines = [line.rstrip() for line in text.splitlines()]
+    body = "\n".join(lines).strip("\n")
+    # Collapse runs of 3+ blank lines down to a single blank line.
+    body = _BLANK_RUN.sub("\n\n", body)
+    # Ensure the document opens with a level-1 heading.
+    has_heading = body.lstrip().startswith("#")
+    if not has_heading and title:
+        body = f"# {title}\n\n{body}"
+    return body.rstrip("\n") + "\n"
+
+
+class MarkdownNormalizeStep(Step):
+    name = "normalize_markdown"
+
+    def run(self, ctx: StepContext) -> StepResult:
+        ws = task_workspace(ctx.config, ctx.task)
+        text = read_source(ws)
+        title = ctx.task.get("name") or "Document"
+        normalized = normalize(text, title=title)
+        (ws / "normalized.md").write_text(normalized, encoding="utf-8")
+        return StepResult(message=f"normalized to {len(normalized.splitlines())} lines")

runspool/builtin_steps/text_classify.py

@@ -0,0 +1,69 @@
+"""classify_text: assign a coarse category to the source text by keyword match.
+
+Deterministic and offline: a tiny keyword model, not machine learning. It is
+meant to show how a step turns input into a structured artifact that later steps
+(or an operator) can branch on.
+"""
+
+from __future__ import annotations
+
+import json
+
+from runspool.builtin_steps.workspace import read_source, task_workspace
+from runspool.engine.step import Step, StepContext, StepResult
+
+# Ordered so the first category with the most matches wins ties predictably.
+_CATEGORIES: dict[str, tuple[str, ...]] = {
+    "invoice": ("invoice", "amount due", "subtotal", "tax", "total", "bill to", "payment terms"),
+    "support_ticket": (
+        "ticket",
+        "issue",
+        "error",
+        "bug",
+        "cannot",
+        "can't",
+        "broken",
+        "support",
+        "reproduce",
+    ),
+    "meeting_notes": (
+        "meeting",
+        "agenda",
+        "attendees",
+        "action item",
+        "action items",
+        "next steps",
+        "minutes",
+        "discussed",
+    ),
+}
+
+
+def classify(text: str) -> dict:
+    lower = text.lower()
+    scores: dict[str, list[str]] = {}
+    for category, keywords in _CATEGORIES.items():
+        hits = [kw for kw in keywords if kw in lower]
+        if hits:
+            scores[category] = hits
+    if not scores:
+        return {"category": "general", "confidence": 0.0, "matched_keywords": []}
+    best = max(scores, key=lambda c: len(scores[c]))
+    hits = scores[best]
+    confidence = round(min(len(hits) / 3.0, 1.0), 2)
+    return {"category": best, "confidence": confidence, "matched_keywords": hits}
+
+
+class TextClassifyStep(Step):
+    name = "classify_text"
+
+    def run(self, ctx: StepContext) -> StepResult:
+        ws = task_workspace(ctx.config, ctx.task)
+        text = read_source(ws)
+        result = classify(text)
+        (ws / "classification.json").write_text(
+            json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        return StepResult(
+            message=f"classified as {result['category']} (confidence {result['confidence']})"
+        )

runspool/builtin_steps/text_summarize.py

@@ -0,0 +1,81 @@
+"""summarize_text: produce a short extractive summary of the normalized document.
+
+Offline and deterministic: counts, leading sentences, and top keywords by
+frequency. No model calls. The point is to demonstrate a step that consumes a
+prior step's artifact and emits a human-facing one.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+
+from runspool.builtin_steps.workspace import task_workspace
+from runspool.engine.step import Step, StepContext, StepResult
+
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+")
+_WORD = re.compile(r"[A-Za-z][A-Za-z'-]+")
+
+# Common words excluded from keyword ranking.
+_STOPWORDS = frozenset(
+    """the a an and or but of to in on for with at by from as is are was were be been
+    being this that these those it its we you they he she them our your their i me my
+    will would can could should may might must shall not no yes do does did have has had
+    if then else when while which who whom whose what where why how all any each more
+    most some such than too very just about into over under again further once""".split()
+)
+
+
+def summarize(text: str, *, max_sentences: int = 3, top_keywords: int = 8) -> dict:
+    # Drop Markdown heading lines from sentence selection.
+    body_lines = [ln for ln in text.splitlines() if not ln.lstrip().startswith("#")]
+    body = " ".join(ln.strip() for ln in body_lines if ln.strip())
+    sentences = [s.strip() for s in _SENTENCE_SPLIT.split(body) if s.strip()]
+    lead = sentences[:max_sentences]
+
+    words = [w.lower() for w in _WORD.findall(text)]
+    meaningful = [w for w in words if w not in _STOPWORDS and len(w) > 2]
+    keywords = [w for w, _ in Counter(meaningful).most_common(top_keywords)]
+
+    return {
+        "word_count": len(words),
+        "sentence_count": len(sentences),
+        "summary_sentences": lead,
+        "keywords": keywords,
+    }
+
+
+def render_markdown(summary: dict, *, title: str) -> str:
+    lines = [f"# Summary: {title}", ""]
+    lines.append(f"- Words: {summary['word_count']}")
+    lines.append(f"- Sentences: {summary['sentence_count']}")
+    if summary["keywords"]:
+        lines.append(f"- Keywords: {', '.join(summary['keywords'])}")
+    lines.append("")
+    lines.append("## Lead")
+    lines.append("")
+    if summary["summary_sentences"]:
+        for s in summary["summary_sentences"]:
+            lines.append(f"- {s}")
+    else:
+        lines.append("- (no extractable sentences)")
+    return "\n".join(lines) + "\n"
+
+
+class TextSummarizeStep(Step):
+    name = "summarize_text"
+
+    def run(self, ctx: StepContext) -> StepResult:
+        ws = task_workspace(ctx.config, ctx.task)
+        normalized_path = ws / "normalized.md"
+        source = normalized_path if normalized_path.exists() else ws / "source.txt"
+        text = source.read_text(encoding="utf-8")
+        title = ctx.task.get("name") or "Document"
+
+        summary = summarize(text)
+        (ws / "summary.json").write_text(
+            json.dumps(summary, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        (ws / "summary.md").write_text(render_markdown(summary, title=title), encoding="utf-8")
+        return StepResult(message=f"summarized {summary['word_count']} words")

runspool/builtin_steps/workspace.py

@@ -0,0 +1,44 @@
+"""Task workspace helpers.
+
+The filesystem is the artifact store. Each task gets an isolated directory under
+``<workspace_root>/tasks/<id>/``; steps read and write files there.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def task_workspace(config: Any, task: dict[str, Any]) -> Path:
+    """Return (creating if needed) the working directory for a task."""
+    ws = Path(config.workspace_root) / "tasks" / str(task["id"])
+    ws.mkdir(parents=True, exist_ok=True)
+    return ws
+
+
+def archive_dir(config: Any, task: dict[str, Any]) -> Path:
+    """Return the destination directory for an archived task."""
+    return Path(config.workspace_root) / "ready" / str(task["id"])
+
+
+def read_source(ws: Path) -> str:
+    """Read the canonical source text written by the intake step."""
+    return (ws / "source.txt").read_text(encoding="utf-8")
+
+
+def list_artifacts(config: Any, task: dict[str, Any]) -> list[str]:
+    """List artifact files for a task as paths relative to ``workspace_root``.
+
+    Looks in both the active task directory and the archived directory, so a
+    completed (archived) task still reports its outputs.
+    """
+    root = Path(config.workspace_root)
+    found: list[str] = []
+    for base in (root / "tasks" / str(task["id"]), root / "ready" / str(task["id"])):
+        if not base.exists():
+            continue
+        for path in sorted(base.rglob("*")):
+            if path.is_file():
+                found.append(str(path.relative_to(root)))
+    return found