pac-pincers 0.1.0__tar.gz

pac_pincers-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: pac-pincers
+Version: 0.1.0
+Summary: Local stdio MCP server for CSV/Excel data manipulation via Polars virtual files
+Requires-Python: >=3.11
+Requires-Dist: fastexcel>=0.12.0
+Requires-Dist: mcp[cli]>=1.3.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: polars>=1.0.0
+Requires-Dist: uuid7>=0.1.0
+Requires-Dist: xlsxwriter>=3.2.0

pac_pincers-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pac-pincers"
+version = "0.1.0"
+description = "Local stdio MCP server for CSV/Excel data manipulation via Polars virtual files"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.3.0",
+    "polars>=1.0.0",
+    "uuid7>=0.1.0",
+    "openpyxl>=3.1.0",
+    "xlsxwriter>=3.2.0",
+    "fastexcel>=0.12.0",
+]
+
+[project.scripts]
+pac-pincers = "pac_pincers.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pac_pincers"]

pac_pincers-0.1.0/src/pac_pincers/__init__.py

@@ -0,0 +1 @@
+"""pac-pincers: Local stdio MCP server for CSV/Excel manipulation via Polars virtual files."""

pac_pincers-0.1.0/src/pac_pincers/__main__.py

@@ -0,0 +1,9 @@
+from .server import mcp
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pac_pincers-0.1.0/src/pac_pincers/_transforms.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any
+
+import polars as pl
+
+
+_AGG_FN_MAP: dict[str, Any] = {
+    "sum":      lambda c: c.sum(),
+    "mean":     lambda c: c.mean(),
+    "min":      lambda c: c.min(),
+    "max":      lambda c: c.max(),
+    "count":    lambda c: c.count(),
+    "std":      lambda c: c.std(),
+    "var":      lambda c: c.var(),
+    "first":    lambda c: c.first(),
+    "last":     lambda c: c.last(),
+    "median":   lambda c: c.median(),
+    "n_unique": lambda c: c.n_unique(),
+}
+
+
+def aggregate(
+    df: pl.DataFrame,
+    group_by: list[str] | None,
+    aggregations: list[dict],
+) -> pl.DataFrame:
+    agg_exprs = []
+    for agg in aggregations:
+        col = pl.col(agg["column"])
+        fn_name = agg["function"]
+        if fn_name not in _AGG_FN_MAP:
+            raise ValueError(
+                f"Unknown aggregation function {fn_name!r}. "
+                f"Valid: {sorted(_AGG_FN_MAP)}"
+            )
+        expr = _AGG_FN_MAP[fn_name](col)
+        if alias := agg.get("alias"):
+            expr = expr.alias(alias)
+        agg_exprs.append(expr)
+
+    if group_by:
+        return df.group_by(group_by).agg(agg_exprs)
+    return df.select(agg_exprs)
+
+
+def filter_rows(
+    df: pl.DataFrame,
+    conditions: list[dict],
+    logic: str = "and",
+) -> pl.DataFrame:
+    if not conditions:
+        return df
+
+    exprs: list[pl.Expr] = []
+    for cond in conditions:
+        col = pl.col(cond["column"])
+        op = cond["operator"]
+        val: Any = cond.get("value")
+
+        match op:
+            case "=":           expr = col == val
+            case "!=":          expr = col != val
+            case ">":           expr = col > val
+            case ">=":          expr = col >= val
+            case "<":           expr = col < val
+            case "<=":          expr = col <= val
+            case "contains":    expr = col.str.contains(val)
+            case "starts_with": expr = col.str.starts_with(val)
+            case "ends_with":   expr = col.str.ends_with(val)
+            case "in":          expr = col.is_in(val)
+            case "not_in":      expr = ~col.is_in(val)
+            case "is_null":     expr = col.is_null()
+            case "is_not_null": expr = col.is_not_null()
+            case _:             raise ValueError(f"Unknown filter operator {op!r}")
+        exprs.append(expr)
+
+    combined = exprs[0]
+    for e in exprs[1:]:
+        combined = (combined & e) if logic == "and" else (combined | e)
+    return df.filter(combined)
+
+
+def sort_rows(df: pl.DataFrame, by: list[dict]) -> pl.DataFrame:
+    columns = [b["column"] for b in by]
+    descending = [b.get("descending", False) for b in by]
+    return df.sort(columns, descending=descending)
+
+
+def join_frames(
+    left: pl.DataFrame,
+    right: pl.DataFrame,
+    left_on: list[str],
+    right_on: list[str],
+    how: str,
+) -> pl.DataFrame:
+    valid = {"inner", "left", "right", "full", "semi", "anti", "cross"}
+    if how not in valid:
+        raise ValueError(f"Unknown join type {how!r}. Valid: {sorted(valid)}")
+    return left.join(right, left_on=left_on, right_on=right_on, how=how)  # type: ignore[arg-type]

pac_pincers-0.1.0/src/pac_pincers/server.py

@@ -0,0 +1,497 @@
+from __future__ import annotations
+
+import shutil
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any, Optional
+
+import polars as pl
+from mcp.server.fastmcp import FastMCP
+
+from .store import VirtualFileStore
+from . import _transforms as T
+
+
+mcp = FastMCP(
+    "pac-pincers",
+    instructions=(
+        "Local stdio MCP for in-memory CSV/Excel manipulation. "
+        "Files are loaded as 'virtual files' (Polars DataFrames) identified by unique IDs. "
+        "Transform tools delete the source virtual file and replace it with the result "
+        "unless keep_original=True."
+    ),
+)
+_store = VirtualFileStore()
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _read_file(path: str) -> pl.DataFrame:
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    ext = p.suffix.lower()
+    if ext == ".csv":
+        return pl.read_csv(p)
+    if ext in (".xlsx", ".xls", ".xlsm"):
+        return pl.read_excel(p)
+    raise ValueError(f"Unsupported format {ext!r} — use .csv or .xlsx/.xls/.xlsm")
+
+
+def _write_file(df: pl.DataFrame, path: str) -> None:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    ext = p.suffix.lower()
+    if ext == ".csv":
+        df.write_csv(p)
+    elif ext in (".xlsx", ".xls", ".xlsm"):
+        df.write_excel(p)
+    else:
+        raise ValueError(f"Unsupported format {ext!r} — use .csv or .xlsx")
+
+
+def _safe(v: Any) -> Any:
+    if isinstance(v, (datetime, date)):
+        return v.isoformat()
+    return v
+
+
+def _paginate(df: pl.DataFrame, offset: int, limit: int) -> dict:
+    sliced = df.slice(offset, limit)
+    return {
+        "total_rows": df.height,
+        "offset": offset,
+        "limit": limit,
+        "rows_returned": sliced.height,
+        "columns": list(df.columns),
+        "schema": {col: str(dtype) for col, dtype in df.schema.items()},
+        "data": [{k: _safe(v) for k, v in row.items()} for row in sliced.to_dicts()],
+    }
+
+
+def _vf_meta(vf_id: str, df: pl.DataFrame) -> dict:
+    return {
+        "id": vf_id,
+        "rows": df.height,
+        "columns": list(df.columns),
+    }
+
+
+# ── virtual file operations ───────────────────────────────────────────────────
+
+@mcp.tool()
+def list_virtual_files() -> list[dict]:
+    """List all virtual files currently held in memory.
+
+    A virtual file is a named Polars DataFrame kept in server memory.
+    Each has a unique ID with format `{name}__{uuid7hex}`.
+    Returns metadata only (no row data). Use `get` to retrieve rows.
+
+    Returns: list of { id, source, rows, columns, schema }
+    """
+    return _store.list_all()
+
+
+@mcp.tool()
+def load(path: str, id: Optional[str] = None) -> dict:
+    """Load a CSV or Excel file from disk into a new virtual file in memory.
+
+    Reads the file at `path` into a Polars DataFrame and registers it as a virtual
+    file. Supports .csv, .xlsx, .xls, .xlsm. The returned `id` is the handle for
+    all subsequent operations on this data. The disk file is not modified.
+
+    Args:
+        path: Absolute or relative path to the source file.
+        id:   Optional custom ID (must be unique). Auto-generated from filename if omitted.
+
+    Returns: { id, source, rows, columns, schema }
+    """
+    df = _read_file(path)
+    vf = _store.add(df, Path(path).stem, id=id, source=str(path))
+    return {
+        "id": vf.id,
+        "source": vf.source,
+        "rows": df.height,
+        "columns": list(df.columns),
+        "schema": {col: str(dtype) for col, dtype in df.schema.items()},
+    }
+
+
+@mcp.tool()
+def dump(id: str, path: str) -> dict:
+    """Write a virtual file from memory to a disk file.
+
+    Serialises the virtual file identified by `id` to `path`. Format is inferred from
+    the extension: .csv → CSV, .xlsx/.xls/.xlsm → Excel. Parent directories are
+    created if missing. The virtual file remains in memory unchanged.
+
+    Args:
+        id:   ID of the virtual file to write.
+        path: Destination path (extension determines format).
+
+    Returns: { id, path, rows }
+    """
+    vf = _store.get(id)
+    _write_file(vf.df, path)
+    return {"id": id, "path": str(path), "rows": vf.df.height}
+
+
+@mcp.tool()
+def delete(id: str) -> dict:
+    """Remove a virtual file from memory.
+
+    Frees the in-memory DataFrame. Does NOT touch any disk file.
+    The ID becomes invalid immediately. Use `copy` first if you need to keep the data.
+
+    Args:
+        id: ID of the virtual file to remove.
+
+    Returns: { deleted_id }
+    """
+    _store.delete(id)
+    return {"deleted_id": id}
+
+
+@mcp.tool()
+def rename(id: str, new_name: str, new_id: Optional[str] = None) -> dict:
+    """Rename a virtual file — assigns it a new ID, old ID is invalidated.
+
+    Re-registers the virtual file under a new ID derived from `new_name`
+    (format: `new_name__{uuid7hex}`). Supply `new_id` to set the full ID explicitly.
+    The DataFrame content is unchanged. The old ID must not be used after this call.
+
+    Args:
+        id:       Current ID of the virtual file.
+        new_name: Base name for the new auto-generated ID (ignored if new_id is given).
+        new_id:   Optional fully custom new ID (must be unique).
+
+    Returns: { old_id, new_id }
+    """
+    old_id = id
+    vf = _store.rename(id, new_name, new_id=new_id)
+    return {"old_id": old_id, "new_id": vf.id}
+
+
+@mcp.tool()
+def copy(id: str, new_id: Optional[str] = None) -> dict:
+    """Duplicate a virtual file, creating a new independent virtual file.
+
+    Deep-copies the DataFrame and registers it under a new ID. The original virtual
+    file is unchanged.
+
+    Args:
+        id:     ID of the virtual file to copy.
+        new_id: Optional custom ID for the copy (must be unique).
+
+    Returns: { source_id, new_id }
+    """
+    new_vf = _store.copy(id, new_id=new_id)
+    return {"source_id": id, "new_id": new_vf.id}
+
+
+@mcp.tool()
+def get(id: str, offset: int = 0, limit: int = 100) -> dict:
+    """Read paginated rows from a virtual file.
+
+    Returns at most `limit` rows starting at `offset`. Always includes `total_rows`
+    so you can determine whether more pages exist. Advance with offset += limit.
+
+    Args:
+        id:     ID of the virtual file.
+        offset: First row index to return (0-based, default 0).
+        limit:  Max rows to return (default 100).
+
+    Returns: { id, total_rows, offset, limit, rows_returned, columns, schema, data }
+    """
+    vf = _store.get(id)
+    result = _paginate(vf.df, offset, limit)
+    result["id"] = id
+    return result
+
+
+# ── local (disk) file operations ─────────────────────────────────────────────
+
+@mcp.tool()
+def delete_local(path: str) -> dict:
+    """Delete a file from disk. Does not affect any virtual file in memory.
+
+    Args:
+        path: Path to the file to delete.
+
+    Returns: { deleted_path }
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    p.unlink()
+    return {"deleted_path": str(path)}
+
+
+@mcp.tool()
+def rename_local(path: str, new_path: str) -> dict:
+    """Rename (move) a file on disk. Does not affect any virtual file in memory.
+
+    Args:
+        path:     Current file path.
+        new_path: New file path. Parent directory must already exist.
+
+    Returns: { old_path, new_path }
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    p.rename(new_path)
+    return {"old_path": str(path), "new_path": str(new_path)}
+
+
+@mcp.tool()
+def copy_local(path: str, dest: str) -> dict:
+    """Copy a file on disk to a new location. Does not affect any virtual file in memory.
+
+    Args:
+        path: Source file path.
+        dest: Destination file path.
+
+    Returns: { source, dest }
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    shutil.copy2(str(p), str(dest))
+    return {"source": str(path), "dest": str(dest)}
+
+
+@mcp.tool()
+def get_local(path: str, offset: int = 0, limit: int = 100) -> dict:
+    """Read paginated rows directly from a disk file without creating a virtual file.
+
+    Reads a CSV or Excel file, returns a page of rows, then discards the data.
+    Use this to inspect a file before deciding whether to load it into memory.
+
+    Args:
+        path:   Path to the CSV or Excel file.
+        offset: First row index to return (0-based, default 0).
+        limit:  Max rows to return (default 100).
+
+    Returns: { path, total_rows, offset, limit, rows_returned, columns, schema, data }
+    """
+    df = _read_file(path)
+    result = _paginate(df, offset, limit)
+    result["path"] = str(path)
+    return result
+
+
+# ── transform operations ──────────────────────────────────────────────────────
+#
+# All transforms produce a NEW virtual file and return its ID.
+#
+# keep_original=False (default):
+#   The source virtual file is DELETED; the result takes a new auto-generated ID
+#   (or the ID given via new_id). Use this when you want to replace the source.
+#
+# keep_original=True:
+#   The source virtual file is KEPT unchanged; the result is a separate new entry.
+#   Supply new_id to control the result's ID; otherwise it is auto-generated.
+#
+# new_id must be unique across all virtual files or the call returns an error.
+# All transforms return { result_id, source_id, rows, columns }.
+
+
+@mcp.tool()
+def aggregate(
+    id: str,
+    aggregations: list[dict],
+    group_by: Optional[list[str]] = None,
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Group and aggregate a virtual file's rows.
+
+    Each entry in `aggregations`:
+      { "column": str, "function": str, "alias": str (optional) }
+
+    Supported functions: sum, mean, min, max, count, std, var, first, last, median, n_unique.
+
+    `group_by`: list of column names to group by. Omit for a global (single-row) aggregate.
+
+    Args:
+        id:           Source virtual file ID.
+        aggregations: List of aggregation specs (see above).
+        group_by:     Columns to group by (optional).
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep source virtual file (default False — source is deleted).
+
+    Returns: { result_id, source_id, rows, columns }
+    """
+    vf = _store.get(id)
+    result_df = T.aggregate(vf.df, group_by, aggregations)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id}
+
+
+@mcp.tool()
+def filter_rows(
+    id: str,
+    conditions: list[dict],
+    logic: str = "and",
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Filter rows of a virtual file by one or more conditions.
+
+    Each condition:
+      { "column": str, "operator": str, "value": any }
+    Omit "value" for is_null / is_not_null operators.
+
+    Operators: =, !=, >, >=, <, <=, contains, starts_with, ends_with,
+               in, not_in, is_null, is_not_null.
+    `in` / `not_in` require value to be a list.
+
+    `logic`: "and" | "or" — how multiple conditions are combined (default "and").
+
+    Args:
+        id:           Source virtual file ID.
+        conditions:   List of filter conditions (see above).
+        logic:        Combine conditions with "and" or "or" (default "and").
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep source virtual file (default False — source is deleted).
+
+    Returns: { result_id, source_id, rows, columns }
+    """
+    vf = _store.get(id)
+    result_df = T.filter_rows(vf.df, conditions, logic)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id}
+
+
+@mcp.tool()
+def select_columns(
+    id: str,
+    columns: list[str],
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Retain only the specified columns, dropping all others.
+
+    Args:
+        id:           Source virtual file ID.
+        columns:      Ordered list of column names to keep.
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep source virtual file (default False — source is deleted).
+
+    Returns: { result_id, source_id, rows, columns }
+    """
+    vf = _store.get(id)
+    result_df = vf.df.select(columns)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id}
+
+
+@mcp.tool()
+def rename_columns(
+    id: str,
+    mapping: dict[str, str],
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Rename one or more columns. Columns not listed in mapping are unchanged.
+
+    Args:
+        id:           Source virtual file ID.
+        mapping:      { "old_name": "new_name", ... }
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep source virtual file (default False — source is deleted).
+
+    Returns: { result_id, source_id, rows, columns }
+    """
+    vf = _store.get(id)
+    result_df = vf.df.rename(mapping)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id}
+
+
+@mcp.tool()
+def sort(
+    id: str,
+    by: list[dict],
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Sort rows by one or more columns.
+
+    Each entry in `by`:
+      { "column": str, "descending": bool (default false) }
+    Rows are sorted by the first key, ties broken by subsequent keys.
+
+    Args:
+        id:           Source virtual file ID.
+        by:           List of sort keys (see above).
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep source virtual file (default False — source is deleted).
+
+    Returns: { result_id, source_id, rows, columns }
+    """
+    vf = _store.get(id)
+    result_df = T.sort_rows(vf.df, by)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id}
+
+
+@mcp.tool()
+def join(
+    id: str,
+    right_id: str,
+    left_on: list[str],
+    right_on: list[str],
+    how: str = "inner",
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Join two virtual files into a new virtual file.
+
+    `id` is the left table; `right_id` is the right table. Both must already be
+    loaded as virtual files. The right virtual file is never modified or deleted.
+    keep_original applies to the left table only.
+
+    `left_on` / `right_on`: parallel lists of join-key column names.
+    `how`: inner | left | right | full | semi | anti | cross (default inner).
+
+    Args:
+        id:           Left virtual file ID.
+        right_id:     Right virtual file ID.
+        left_on:      Key column(s) from the left table.
+        right_on:     Key column(s) from the right table (same length as left_on).
+        how:          Join type (default "inner").
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep the left virtual file (default False — left source is deleted).
+
+    Returns: { result_id, source_id, right_id, rows, columns }
+    """
+    left_vf = _store.get(id)
+    right_vf = _store.get(right_id)
+    result_df = T.join_frames(left_vf.df, right_vf.df, left_on, right_on, how)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id, "right_id": right_id}
+
+
+@mcp.tool()
+def head(
+    id: str,
+    n: int = 10,
+    new_id: Optional[str] = None,
+    keep_original: bool = False,
+) -> dict:
+    """Keep only the first N rows of a virtual file.
+
+    Args:
+        id:           Source virtual file ID.
+        n:            Number of rows to keep (default 10).
+        new_id:       Custom ID for the result virtual file (auto-generated if omitted).
+        keep_original: Keep source virtual file (default False — source is deleted).
+
+    Returns: { result_id, source_id, rows, columns }
+    """
+    vf = _store.get(id)
+    result_df = vf.df.head(n)
+    new_vf = _store.apply_transform(id, result_df, new_id=new_id, keep_original=keep_original)
+    return _vf_meta(new_vf.id, result_df) | {"source_id": id}

pac_pincers-0.1.0/src/pac_pincers/store.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import polars as pl
+from uuid_extensions import uuid7 as _uuid7
+
+
+def _new_uuid() -> str:
+    return _uuid7().hex
+
+
+@dataclass
+class VirtualFile:
+    id: str
+    df: pl.DataFrame
+    source: Optional[str] = None  # original file path, if any
+
+
+class VirtualFileStore:
+    def __init__(self) -> None:
+        self._files: dict[str, VirtualFile] = {}
+
+    def _gen_id(self, name: str) -> str:
+        stem = Path(name).stem if name else "virtual"
+        stem = "".join(c if c.isalnum() or c == "_" else "_" for c in stem)
+        while True:
+            candidate = f"{stem}__{_new_uuid()}"
+            if candidate not in self._files:
+                return candidate
+
+    def add(
+        self,
+        df: pl.DataFrame,
+        name: str,
+        *,
+        id: Optional[str] = None,
+        source: Optional[str] = None,
+    ) -> VirtualFile:
+        if id is None:
+            id = self._gen_id(name)
+        elif id in self._files:
+            raise ValueError(f"Virtual file id already exists: {id!r}")
+        vf = VirtualFile(id=id, df=df, source=source)
+        self._files[id] = vf
+        return vf
+
+    def get(self, id: str) -> VirtualFile:
+        try:
+            return self._files[id]
+        except KeyError:
+            raise KeyError(f"Virtual file not found: {id!r}")
+
+    def delete(self, id: str) -> None:
+        self.get(id)
+        del self._files[id]
+
+    def rename(self, id: str, new_name: str, *, new_id: Optional[str] = None) -> VirtualFile:
+        """Re-register the virtual file under a new ID derived from new_name (or custom new_id). Old ID is removed."""
+        vf = self.get(id)
+        if new_id is None:
+            new_id = self._gen_id(new_name)
+        elif new_id in self._files:
+            raise ValueError(f"Virtual file id already exists: {new_id!r}")
+        new_vf = VirtualFile(id=new_id, df=vf.df, source=vf.source)
+        self._files[new_id] = new_vf
+        del self._files[id]
+        return new_vf
+
+    def copy(self, id: str, *, new_id: Optional[str] = None) -> VirtualFile:
+        """Duplicate a virtual file; original is kept."""
+        vf = self.get(id)
+        stem = id.split("__")[0]
+        if new_id is None:
+            new_id = self._gen_id(stem)
+        elif new_id in self._files:
+            raise ValueError(f"Virtual file id already exists: {new_id!r}")
+        new_vf = VirtualFile(id=new_id, df=vf.df.clone(), source=vf.source)
+        self._files[new_id] = new_vf
+        return new_vf
+
+    def apply_transform(
+        self,
+        source_id: str,
+        result_df: pl.DataFrame,
+        *,
+        new_id: Optional[str] = None,
+        keep_original: bool = False,
+    ) -> VirtualFile:
+        """Store result_df as a new virtual file. Removes source_id unless keep_original is True."""
+        source = self.get(source_id)
+        stem = source_id.split("__")[0]
+        new_vf = self.add(result_df, stem, id=new_id, source=source.source)
+        if not keep_original:
+            del self._files[source_id]
+        return new_vf
+
+    def list_all(self) -> list[dict]:
+        return [
+            {
+                "id": vf.id,
+                "source": vf.source,
+                "rows": vf.df.height,
+                "columns": list(vf.df.columns),
+                "schema": {col: str(dtype) for col, dtype in vf.df.schema.items()},
+            }
+            for vf in self._files.values()
+        ]