vial-ml 0.1.0__tar.gz

vial_ml-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: vial-ml
+Version: 0.1.0
+Summary: Surgical code isolation for AI agents
+Author: Momchil Georgiev
+Author-email: Momchil Georgiev <40865235+momchilgeorgiev@users.noreply.github.com>
+Requires-Dist: typer>=0.25.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Vial
+
+Surgical code isolation for AI agents.
+
+Vial extracts a single function or class from a large Python file into a clean, focused workspace file so an agent only sees — and edits — exactly what it needs to.
+
+## Install
+
+```bash
+pip install vial
+# or with uv:
+uv add vial
+```
+
+## CLI
+
+```bash
+# Isolate a function
+vial extract billing.py process_payment
+
+# Agent edits .vial_workspace/process_payment_isolated.py ...
+
+# Stitch it back (validates syntax first)
+vial merge
+```
+
+## Python API
+
+```python
+from vial import Vial
+
+v = Vial()
+isolated_path = v.extract("billing.py", "process_payment")
+# agent edits isolated_path ...
+v.merge()
+```
+
+## Why
+
+When an agent reads a 2,000-line file to fix a 20-line function it wastes tokens, risks editing the wrong code, and produces complex diffs that frequently fail. Vial reduces the context to only what matters, cutting token usage by 71–88% on typical files.
+
+## How it works
+
+1. **Extract** — AST-based line-bound finder locates the exact start/end of the target. A protected context header (imports + module-level globals, commented out) is prepended so the agent has the context it needs without being able to accidentally modify it.
+2. **Edit** — The agent modifies only the isolated file.
+3. **Merge** — Vial validates the modified code's syntax, then splices it back into the original file at the exact line range. Surrounding code is never touched.
+
+All session state lives in a `metadata.json` file inside the workspace directory.

vial_ml-0.1.0/README.md

@@ -0,0 +1,48 @@
+# Vial
+
+Surgical code isolation for AI agents.
+
+Vial extracts a single function or class from a large Python file into a clean, focused workspace file so an agent only sees — and edits — exactly what it needs to.
+
+## Install
+
+```bash
+pip install vial
+# or with uv:
+uv add vial
+```
+
+## CLI
+
+```bash
+# Isolate a function
+vial extract billing.py process_payment
+
+# Agent edits .vial_workspace/process_payment_isolated.py ...
+
+# Stitch it back (validates syntax first)
+vial merge
+```
+
+## Python API
+
+```python
+from vial import Vial
+
+v = Vial()
+isolated_path = v.extract("billing.py", "process_payment")
+# agent edits isolated_path ...
+v.merge()
+```
+
+## Why
+
+When an agent reads a 2,000-line file to fix a 20-line function it wastes tokens, risks editing the wrong code, and produces complex diffs that frequently fail. Vial reduces the context to only what matters, cutting token usage by 71–88% on typical files.
+
+## How it works
+
+1. **Extract** — AST-based line-bound finder locates the exact start/end of the target. A protected context header (imports + module-level globals, commented out) is prepended so the agent has the context it needs without being able to accidentally modify it.
+2. **Edit** — The agent modifies only the isolated file.
+3. **Merge** — Vial validates the modified code's syntax, then splices it back into the original file at the exact line range. Surrounding code is never touched.
+
+All session state lives in a `metadata.json` file inside the workspace directory.

vial_ml-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "vial-ml"
+version = "0.1.0"
+description = "Surgical code isolation for AI agents"
+readme = "README.md"
+authors = [
+    { name = "Momchil Georgiev", email = "40865235+momchilgeorgiev@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.25.1",
+]
+
+[project.scripts]
+vial = "vial.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.8.14,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "vial"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/vial"]
+omit = ["*/cli.py"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 85
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+]

vial_ml-0.1.0/src/vial/__init__.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+from vial.workspace import Workspace
+from vial.extractor import find_target
+from vial.context import extract_context
+from vial.merger import validate_syntax, strip_header, splice_back
+
+HEADER_DELIMITER = "#" + "=" * 40 + " END OF CONTEXT " + "=" * 40
+
+
+class Vial:
+    def __init__(self, workspace_dir: str | Path = ".vial_workspace"):
+        self.workspace = Workspace(workspace_dir)
+
+    def extract(self, source_filepath: str | Path, target_name: str) -> str:
+        """Extract target_name from source_filepath into an isolated workspace file."""
+        source = Path(source_filepath)
+        source_code = source.read_text()
+
+        result = find_target(source_code, target_name)
+        context = extract_context(source_code)
+
+        header = "# Context from original file (read-only — do not modify this block):\n"
+        if context:
+            header += "\n".join(f"# {line}" for line in context.splitlines()) + "\n"
+        header += HEADER_DELIMITER + "\n"
+
+        isolated_path = self.workspace.isolated_path(target_name)
+        isolated_path.write_text(header + result.code)
+
+        self.workspace.save_metadata({
+            "source_filepath": str(source.resolve()),
+            "target_name": target_name,
+            "start_line": result.start_line,
+            "end_line": result.end_line,
+            "isolated_filepath": str(isolated_path.resolve()),
+        })
+
+        return str(isolated_path)
+
+    def merge(self) -> None:
+        """Validate and merge the modified isolated file back into the source."""
+        meta = self.workspace.load_metadata()
+        isolated = Path(meta["isolated_filepath"])
+        content = isolated.read_text()
+
+        modified_code = strip_header(content, HEADER_DELIMITER)
+
+        is_valid, error = validate_syntax(modified_code)
+        if not is_valid:
+            raise ValueError(
+                f"Merge aborted — agent produced invalid Python code:\n{error}"
+            )
+
+        splice_back(
+            source_filepath=Path(meta["source_filepath"]),
+            modified_code=modified_code,
+            start_line=meta["start_line"],
+            end_line=meta["end_line"],
+        )
+
+        self.workspace.cleanup()

vial_ml-0.1.0/src/vial/cli.py

@@ -0,0 +1,36 @@
+import typer
+from pathlib import Path
+from vial import Vial
+
+app = typer.Typer(help="Vial — surgical code isolation for AI agents.")
+
+
+@app.command()
+def extract(
+    source: Path = typer.Argument(..., help="Path to the Python source file."),
+    target: str = typer.Argument(..., help="Name of the function or class to extract."),
+    workspace: Path = typer.Option(".vial_workspace", help="Workspace directory."),
+):
+    """Extract a named function or class into an isolated workspace file."""
+    try:
+        v = Vial(workspace_dir=workspace)
+        isolated = v.extract(source, target)
+        typer.echo(f"Isolated '{target}' → {isolated}")
+    except (ValueError, FileNotFoundError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def merge(
+    workspace: Path = typer.Option(".vial_workspace", help="Workspace directory."),
+):
+    """Validate and merge the modified isolated file back into the source."""
+    try:
+        v = Vial(workspace_dir=workspace)
+        meta = v.workspace.load_metadata()
+        v.merge()
+        typer.echo(f"Merged '{meta['target_name']}' back into {meta['source_filepath']}")
+    except (ValueError, FileNotFoundError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)

vial_ml-0.1.0/src/vial/context.py

@@ -0,0 +1,18 @@
+import ast
+
+
+def extract_context(source_code: str) -> str:
+    """Return import statements and top-level assignments as a single string."""
+    if not source_code.strip():
+        return ""
+
+    tree = ast.parse(source_code)
+    lines = source_code.splitlines()
+    collected: list[str] = []
+
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom, ast.Assign, ast.AnnAssign)):
+            chunk = lines[node.lineno - 1 : node.end_lineno]
+            collected.extend(chunk)
+
+    return "\n".join(collected)

vial_ml-0.1.0/src/vial/extractor.py

@@ -0,0 +1,34 @@
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class ExtractionResult:
+    target_name: str
+    start_line: int  # 0-indexed, inclusive
+    end_line: int    # 0-indexed, exclusive
+    code: str
+
+
+def find_target(source_code: str, target_name: str) -> ExtractionResult:
+    """Locate a named function or class and return its bounds and source."""
+    tree = ast.parse(source_code)
+    lines = source_code.splitlines()
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            if node.name == target_name:
+                start = node.lineno - 1
+                end = node.end_lineno
+                code = "\n".join(lines[start:end])
+                return ExtractionResult(
+                    target_name=target_name,
+                    start_line=start,
+                    end_line=end,
+                    code=code,
+                )
+
+    raise ValueError(
+        f"'{target_name}' not found in source. "
+        "Check the name and make sure it is a top-level function or class."
+    )

vial_ml-0.1.0/src/vial/merger.py

@@ -0,0 +1,34 @@
+import ast
+from pathlib import Path
+
+
+def validate_syntax(code: str) -> tuple[bool, str]:
+    """Returns (True, '') if code is valid Python, else (False, error_message)."""
+    try:
+        ast.parse(code)
+        return True, ""
+    except SyntaxError as e:
+        return False, f"SyntaxError on line {e.lineno}: {e.msg}\n{e.text or ''}"
+
+
+def strip_header(content: str, delimiter: str) -> str:
+    """Remove the read-only context header block above the delimiter."""
+    if delimiter in content:
+        _, code = content.split(delimiter, 1)
+        return code.strip("\n")
+    return content.strip("\n")
+
+
+def splice_back(
+    source_filepath: Path,
+    modified_code: str,
+    start_line: int,
+    end_line: int,
+) -> Path:
+    """Replace lines [start_line:end_line] in source_filepath with modified_code."""
+    original_lines = source_filepath.read_text().splitlines()
+    modified_lines = modified_code.splitlines()
+
+    new_lines = original_lines[:start_line] + modified_lines + original_lines[end_line:]
+    source_filepath.write_text("\n".join(new_lines) + "\n")
+    return source_filepath

vial_ml-0.1.0/src/vial/workspace.py

@@ -0,0 +1,31 @@
+import json
+from pathlib import Path
+
+
+class Workspace:
+    METADATA_FILENAME = "metadata.json"
+
+    def __init__(self, directory: Path | str = ".vial_workspace"):
+        self.dir = Path(directory)
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.metadata_path = self.dir / self.METADATA_FILENAME
+
+    def isolated_path(self, target_name: str) -> Path:
+        return self.dir / f"{target_name}_isolated.py"
+
+    def save_metadata(self, meta: dict) -> None:
+        self.metadata_path.write_text(json.dumps(meta, indent=2))
+
+    def load_metadata(self) -> dict:
+        if not self.metadata_path.exists():
+            raise FileNotFoundError(
+                f"No active session found in {self.dir}. Run `vial extract` first."
+            )
+        return json.loads(self.metadata_path.read_text())
+
+    def cleanup(self) -> None:
+        meta = self.load_metadata()
+        isolated = Path(meta["isolated_filepath"])
+        if isolated.exists():
+            isolated.unlink()
+        self.metadata_path.unlink()