starforge-kernel 0.1.0__tar.gz → 0.1.3__tar.gz

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starforge-kernel
-Version: 0.1.0
+Version: 0.1.3
 Summary: *Forge — pipeline canvas, checkpointing, and stale/hydrate execution for the repo you already have open
 Author: Jonathan Potter
 License-Expression: Apache-2.0

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/pyproject.toml

@@ -1,31 +1,31 @@
-[build-system]
-requires = ["setuptools>=68", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-# PyPI name `starforge` is squatted by a dormant Galaxy tool (see DESIGN.md §4);
-# the import name is still `starforge`.
-name = "starforge-kernel"
-version = "0.1.0"
-description = "*Forge — pipeline canvas, checkpointing, and stale/hydrate execution for the repo you already have open"
-readme = "README.md"
-authors = [{ name = "Jonathan Potter" }]
-license = "Apache-2.0"
-requires-python = ">=3.10"
-# Intentionally empty: the decorator must import in microseconds inside user
-# production code, and the kernel runs stdlib-only. pandas/numpy/pyarrow are
-# probed lazily in workers and used only if the workspace env provides them.
-dependencies = []
-
-[project.urls]
-Homepage = "https://github.com/Jonpot/forge"
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0", "pandas>=2.0", "pyarrow>=15.0", "numpy>=1.26"]
-mcp = ["mcp>=1.8"]
-
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI name `starforge` is squatted by a dormant Galaxy tool (see DESIGN.md §4);
+# the import name is still `starforge`.
+name = "starforge-kernel"
+version = "0.1.3"
+description = "*Forge — pipeline canvas, checkpointing, and stale/hydrate execution for the repo you already have open"
+readme = "README.md"
+authors = [{ name = "Jonathan Potter" }]
+license = "Apache-2.0"
+requires-python = ">=3.10"
+# Intentionally empty: the decorator must import in microseconds inside user
+# production code, and the kernel runs stdlib-only. pandas/numpy/pyarrow are
+# probed lazily in workers and used only if the workspace env provides them.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Jonpot/forge"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pandas>=2.0", "pyarrow>=15.0", "numpy>=1.26"]
+mcp = ["mcp>=1.8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/src/starforge/__init__.py

@@ -1,86 +1,86 @@
-"""*Forge — pipeline canvas for the repo you already have open.
-
-This top-level module is the entire public surface that user code touches.
-It must import in microseconds and depend on nothing: the decorator lives in
-production codebases and has to be free. Everything heavy (indexer, engine,
-kernel) lives in submodules that only *Forge itself* imports.
-"""
-
-from __future__ import annotations
-
-__version__ = "0.1.0"
-
-__all__ = ["block", "progress", "BLOCK_ATTR"]
-
-#: Attribute set on decorated functions. The AST indexer matches the decorator
-#: syntactically and never imports user code; this runtime tag exists so user
-#: code and future runtime introspection can also recognize blocks.
-BLOCK_ATTR = "__starforge_block__"
-
-
-def block(fn=None, *, label=None, category=None, outputs=None):
-    """Register a function as a *Forge block.
-
-    Usable bare or with keyword arguments::
-
-        @block
-        def clean(raw: pd.DataFrame) -> pd.DataFrame: ...
-
-        @block(label="Clean AUC Matrix", category="QC", outputs=("clean", "stats"))
-        def clean_auc(raw, min_coverage: float = 0.8): ...
-
-    The decorated function is returned unchanged — behavior under pytest, in
-    CI, or in production is identical whether or not *Forge is anywhere near.
-
-    Args:
-        label: Palette display name. Defaults to the function name, title-cased.
-        category: Palette grouping. Defaults to the defining module's path.
-        outputs: Names for multiple return values (function must return a tuple
-            of the same length). Defaults to a single output named "output".
-
-    Note for palette metadata: the indexer reads ``label``/``category``/
-    ``outputs`` from the *source*, so they must be literals at the decoration
-    site to appear in the palette.
-    """
-
-    def apply(f):
-        setattr(
-            f,
-            BLOCK_ATTR,
-            {
-                "label": label,
-                "category": category,
-                "outputs": tuple(outputs) if outputs is not None else None,
-            },
-        )
-        return f
-
-    if fn is not None:
-        return apply(fn)
-    return apply
-
-
-#: Installed by the *Forge run worker around each block call; None everywhere
-#: else, which keeps progress() a guaranteed no-op in pytest/CI/production.
-_progress_hook = None
-
-
-def progress(current=None, total=None, label=None):
-    """Report block progress to the *Forge canvas.
-
-    Call freely inside a block::
-
-        for i, chunk in enumerate(chunks):
-            progress(i + 1, len(chunks), "fitting folds")
-            ...
-
-    Outside a *Forge run this does nothing and costs one attribute read —
-    safe to leave in production code. Any combination of arguments works:
-    (current, total) renders a determinate bar, label alone updates the text.
-    """
-    hook = _progress_hook
-    if hook is not None:
-        try:
-            hook(current, total, label)
-        except Exception:
-            pass  # progress must never break user code
+"""*Forge — pipeline canvas for the repo you already have open.
+
+This top-level module is the entire public surface that user code touches.
+It must import in microseconds and depend on nothing: the decorator lives in
+production codebases and has to be free. Everything heavy (indexer, engine,
+kernel) lives in submodules that only *Forge itself* imports.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.3"
+
+__all__ = ["block", "progress", "BLOCK_ATTR"]
+
+#: Attribute set on decorated functions. The AST indexer matches the decorator
+#: syntactically and never imports user code; this runtime tag exists so user
+#: code and future runtime introspection can also recognize blocks.
+BLOCK_ATTR = "__starforge_block__"
+
+
+def block(fn=None, *, label=None, category=None, outputs=None):
+    """Register a function as a *Forge block.
+
+    Usable bare or with keyword arguments::
+
+        @block
+        def clean(raw: pd.DataFrame) -> pd.DataFrame: ...
+
+        @block(label="Clean AUC Matrix", category="QC", outputs=("clean", "stats"))
+        def clean_auc(raw, min_coverage: float = 0.8): ...
+
+    The decorated function is returned unchanged — behavior under pytest, in
+    CI, or in production is identical whether or not *Forge is anywhere near.
+
+    Args:
+        label: Palette display name. Defaults to the function name, title-cased.
+        category: Palette grouping. Defaults to the defining module's path.
+        outputs: Names for multiple return values (function must return a tuple
+            of the same length). Defaults to a single output named "output".
+
+    Note for palette metadata: the indexer reads ``label``/``category``/
+    ``outputs`` from the *source*, so they must be literals at the decoration
+    site to appear in the palette.
+    """
+
+    def apply(f):
+        setattr(
+            f,
+            BLOCK_ATTR,
+            {
+                "label": label,
+                "category": category,
+                "outputs": tuple(outputs) if outputs is not None else None,
+            },
+        )
+        return f
+
+    if fn is not None:
+        return apply(fn)
+    return apply
+
+
+#: Installed by the *Forge run worker around each block call; None everywhere
+#: else, which keeps progress() a guaranteed no-op in pytest/CI/production.
+_progress_hook = None
+
+
+def progress(current=None, total=None, label=None):
+    """Report block progress to the *Forge canvas.
+
+    Call freely inside a block::
+
+        for i, chunk in enumerate(chunks):
+            progress(i + 1, len(chunks), "fitting folds")
+            ...
+
+    Outside a *Forge run this does nothing and costs one attribute read —
+    safe to leave in production code. Any combination of arguments works:
+    (current, total) renders a determinate bar, label alone updates the text.
+    """
+    hook = _progress_hook
+    if hook is not None:
+        try:
+            hook(current, total, label)
+        except Exception:
+            pass  # progress must never break user code

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/src/starforge/core/spec.py

@@ -123,4 +123,9 @@ class PipelineDoc:
         return cls.from_json(Path(path).read_text(encoding="utf-8"))
 
     def save(self, path: str | Path) -> None:
-        Path(path).write_text(self.to_json() + "\n", encoding="utf-8")
+        # Atomic: the canvas (or any watcher) must never observe a truncated
+        # or empty file mid-write — agents and humans edit concurrently.
+        target = Path(path)
+        tmp = target.with_name(target.name + ".tmp")
+        tmp.write_text(self.to_json() + "\n", encoding="utf-8")
+        tmp.replace(target)

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/src/starforge/mcp.py

@@ -207,14 +207,11 @@ def main() -> None:
             [
                 "*Forge MCP server",
                 f"  workspace : {Path(default_workspace).resolve()}",
-                "  transport : stdio — waiting for an MCP client to connect on stdin.",
-                "              (Silence is normal: agents launch this server themselves;",
-                "               you rarely need to run it manually.)",
+                "  transport : stdio (waiting for an MCP client on stdin)",
                 f"  tools     : {', '.join(TOOL_NAMES)}",
                 "",
-                "To register with agents, run \"*Forge: Set Up MCP for Agents\" in VS Code,",
-                "or add to your agent's MCP config:",
-                '  { "command": "python", "args": ["-m", "starforge.mcp"] }   (cwd = your repo)',
+                "Register with an agent via \"*Forge: Set Up MCP for Agents\" in VS Code, or:",
+                '  { "command": "python", "args": ["-m", "starforge.mcp"] }   (cwd = repo root)',
                 "",
                 "Ctrl+C to exit.",
             ]
@@ -226,12 +223,24 @@ def main() -> None:
         "starforge",
         instructions=(
             "Author and run *Forge pipelines in this workspace. Blocks are @block-decorated "
-            "functions in the repo (see list_blocks for ids/params/outputs). Pipelines are "
-            ".forge JSON documents (read one for the schema). write_pipeline validates and "
-            "returns per-node staleness; run_pipeline executes only stale nodes and returns "
-            "results; inspect_node shows output previews from checkpoints. Edges target "
-            "parameter NAMES; params left unwired use literals from the doc or signature "
-            f"defaults. Default workspace: {Path(default_workspace).resolve()}"
+            "functions in the repo (see list_blocks for ids/params/outputs); the decorator is "
+            "behavior-neutral, so blocks remain plain callables you can invoke directly when "
+            "testing logic outside a pipeline. New @block functions are picked up automatically "
+            "on save — no registration step. Pipelines are .forge JSON documents shaped like: "
+            '{"schema": "starforge/1", "name": "demo", '
+            '"nodes": [{"id": "n1", "block": "module:function", "params": {"x": 1}, '
+            '"position": {"x": 80, "y": 80}}], '
+            '"edges": [{"id": "e1", "source": "n1", "source_output": "output", '
+            '"target": "n2", "target_param": "data"}]}. '
+            "Canvas annotation boxes live in a top-level \"comments\" array, each shaped "
+            '{"id": "c1", "title": "...", "description": "...", "position": {"x": 0, "y": 0}, '
+            '"width": 280, "height": 150, "color": "#6366f1"} — these exact field names; '
+            "comments never affect execution. "
+            "Edges target parameter NAMES; unwired params use doc literals or signature "
+            "defaults; `T | None` params with no default receive None. write_pipeline "
+            "validates and returns per-node staleness; run_pipeline executes only stale nodes "
+            "(pass `target` to run one node's ancestor cone); inspect_node returns checkpoint "
+            f"previews. Default workspace: {Path(default_workspace).resolve()}"
         ),
     )
 

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/src/starforge_kernel.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starforge-kernel
-Version: 0.1.0
+Version: 0.1.3
 Summary: *Forge — pipeline canvas, checkpointing, and stale/hydrate execution for the repo you already have open
 Author: Jonathan Potter
 License-Expression: Apache-2.0

{starforge_kernel-0.1.0 → starforge_kernel-0.1.3}/tests/test_mcp_module.py

@@ -23,6 +23,9 @@ def test_write_read_list_state_roundtrip(workspace):
     assert mcp.list_pipelines(ws) == [".forge/pipelines/demo.forge"]
     doc = mcp.read_pipeline(ws, ".forge/pipelines/demo.forge")
     assert [n["id"] for n in doc["nodes"]] == ["n1", "n2", "n3"]
+    # Saves are atomic — no temp residue for watchers to trip over.
+    pipelines_dir = workspace.root / ".forge" / "pipelines"
+    assert [p.name for p in pipelines_dir.glob("*.tmp")] == []
 
 
 def test_write_pipeline_rejects_bad_docs_and_escapes(workspace):