snail-dsl 0.1.0__tar.gz

snail_dsl-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Tico Internet LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

snail_dsl-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: snail-dsl
+Version: 0.1.0
+Summary: Single Node Activated Inference Layer — a Python DSL for composing frozen neural primitives into typed dataflow programs.
+Author: Tico Internet LLC
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/lordxmen2k/SNAIL-DSL
+Project-URL: Repository, https://github.com/lordxmen2k/SNAIL-DSL
+Keywords: ai,ml,dsl,frozen-models,dataflow,neural-networks,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# SNAIL — Single Node Activated Inference Layer
+
+A Python DSL for composing **frozen, single-pass neural primitives** into **statically-typed dataflow programs**.
+
+If an MCP tool and a markdown skill had a baby, and you told the LLM it wasn't allowed to interpret the recipe — it was just one of many nodes in the recipe — you'd get SNAIL.
+
+## Why
+
+Most AI models are trained to be comprehensive. SNAIL trains tiny, single-task nodes — **activated exactly once**, **locked output**, **frozen forever** — and composes them into deterministic graphs.
+
+A SNAIL program is a **recipe that's more resilient than a `.md` spec** and **more deterministic than an MCP tool call**. Every step is a typed function call, not a prompt the LLM might re-interpret. Every run emits a manifest. Every node knows what it doesn't know (OOD is a first-class type).
+
+## Install
+
+```bash
+pip install snail-dsl
+```
+
+## Quick start
+
+```python
+from snail import node, Program, edge
+from pydantic import BaseModel
+
+# Declare the type contract for each node's output.
+class InvoiceTotal(BaseModel):
+    ok: dict | None = None       # { "total": float, "currency": str, "confidence": float }
+    ood: dict | None = None      # { "reason": str, "confidence": float, "threshold": float }
+
+@node(
+    name="extract_invoice_total",
+    input_schema=dict,            # replace with a real pydantic model
+    output_schema=InvoiceTotal,
+    distribution="synthetic_invoices_v2",
+    frozen_weights="weights/extract_invoice_total_v3.snail",
+    confidence_threshold=0.7,
+)
+def extract_invoice_total(ctx, weights, image):
+    raw = weights.model.forward(image["tensor"])
+    return InvoiceTotal(ok={
+        "total": raw["total"],
+        "currency": raw["currency"],
+        "confidence": raw["confidence"],
+    })
+
+# Compose into a typed DAG.
+invoice_pipeline = Program(
+    name="invoice_pipeline_v1",
+    nodes=[extract_invoice_total],
+    edges=[],
+)
+
+result = invoice_pipeline.run({"image_path": "scan.png"})
+print(result.manifest)
+```
+
+The decorator enforces:
+
+- Single forward pass per call — no retries, no second thoughts.
+- Weights loaded once, frozen for the lifetime of the program.
+- Output type-checked against `output_schema`; mismatches become OOD.
+- Confidence below `confidence_threshold` is silently flipped to OOD.
+- Output is locked (immutable) before being handed back to the caller.
+
+## The four primitives
+
+| Primitive | What it does |
+|---|---|
+| `@node` | Decorator that wraps a Python function as a frozen, single-pass, OOD-aware node. |
+| `Program` | Container that builds a typed DAG of nodes. Validates at construction time. |
+| `edge()` | Builder for typed field-to-field connections between nodes. |
+| `manifest` | Structured per-run log: which nodes fired, what they got, what they returned. |
+
+## Architecture
+
+- **Nodes** are frozen, single forward pass, locked output.
+- **Composition** is a static DAG declared in Python.
+- **Training** is 100% synthetic, offline.
+- **OOD** is a first-class type (Ok / OOD discriminated union).
+- **Every node ships with golden tests** (`pytest`).
+- **Every run emits a manifest.**
+
+## Wrapping external models
+
+External models (HuggingFace, hosted APIs, pure functions) become nodes through wrappers. They never get called directly.
+
+```python
+from snail.wrappers import ExternalLocalNode, HostedNode, DeterministicNode
+
+# Pin a local model to exact weights hash
+classify_layout = ExternalLocalNode(
+    name="classify_layout",
+    input_schema=InvoiceImage,
+    output_schema=LayoutClass,
+    distribution="rvl_cdip_subset",
+    call=lambda img: yolo_model.predict(img.path),
+    weight_pin="yolov8n@sha256:abc123...",
+)
+
+# Wrap a hosted API
+summarize = HostedNode(
+    name="summarize",
+    input_schema=InvoiceText,
+    output_schema=InvoiceSummary,
+    endpoint="anthropic://claude-sonnet-4-5",
+    prompt_template="Summarize: {text}",
+    api_key_env="ANTHROPIC_API_KEY",
+)
+
+# Or just a pure function
+validate_email = DeterministicNode(
+    name="validate_email",
+    input_schema=EmailField,
+    output_schema=EmailValidated,
+    fn=lambda x: x if "@" in x.value else None,
+    ood_on_none=True,
+)
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Golden tests live in `tests/golden/`. The lint rule (catches direct `import openai`, `import anthropic`, etc. outside wrappers) is enforced via the `snail.lint` module.
+
+## License
+
+Apache License 2.0. Copyright 2026 Tico Internet LLC.
+
+## Status
+
+v0.1.0 — alpha. The core primitives (`@node`, `Program`, `edge()`, wrappers, manifest, lint) are working. The training pipeline for producing `.snail` weights is not yet included — that ships in v0.2.0.

snail_dsl-0.1.0/README.md

@@ -0,0 +1,135 @@
+# SNAIL — Single Node Activated Inference Layer
+
+A Python DSL for composing **frozen, single-pass neural primitives** into **statically-typed dataflow programs**.
+
+If an MCP tool and a markdown skill had a baby, and you told the LLM it wasn't allowed to interpret the recipe — it was just one of many nodes in the recipe — you'd get SNAIL.
+
+## Why
+
+Most AI models are trained to be comprehensive. SNAIL trains tiny, single-task nodes — **activated exactly once**, **locked output**, **frozen forever** — and composes them into deterministic graphs.
+
+A SNAIL program is a **recipe that's more resilient than a `.md` spec** and **more deterministic than an MCP tool call**. Every step is a typed function call, not a prompt the LLM might re-interpret. Every run emits a manifest. Every node knows what it doesn't know (OOD is a first-class type).
+
+## Install
+
+```bash
+pip install snail-dsl
+```
+
+## Quick start
+
+```python
+from snail import node, Program, edge
+from pydantic import BaseModel
+
+# Declare the type contract for each node's output.
+class InvoiceTotal(BaseModel):
+    ok: dict | None = None       # { "total": float, "currency": str, "confidence": float }
+    ood: dict | None = None      # { "reason": str, "confidence": float, "threshold": float }
+
+@node(
+    name="extract_invoice_total",
+    input_schema=dict,            # replace with a real pydantic model
+    output_schema=InvoiceTotal,
+    distribution="synthetic_invoices_v2",
+    frozen_weights="weights/extract_invoice_total_v3.snail",
+    confidence_threshold=0.7,
+)
+def extract_invoice_total(ctx, weights, image):
+    raw = weights.model.forward(image["tensor"])
+    return InvoiceTotal(ok={
+        "total": raw["total"],
+        "currency": raw["currency"],
+        "confidence": raw["confidence"],
+    })
+
+# Compose into a typed DAG.
+invoice_pipeline = Program(
+    name="invoice_pipeline_v1",
+    nodes=[extract_invoice_total],
+    edges=[],
+)
+
+result = invoice_pipeline.run({"image_path": "scan.png"})
+print(result.manifest)
+```
+
+The decorator enforces:
+
+- Single forward pass per call — no retries, no second thoughts.
+- Weights loaded once, frozen for the lifetime of the program.
+- Output type-checked against `output_schema`; mismatches become OOD.
+- Confidence below `confidence_threshold` is silently flipped to OOD.
+- Output is locked (immutable) before being handed back to the caller.
+
+## The four primitives
+
+| Primitive | What it does |
+|---|---|
+| `@node` | Decorator that wraps a Python function as a frozen, single-pass, OOD-aware node. |
+| `Program` | Container that builds a typed DAG of nodes. Validates at construction time. |
+| `edge()` | Builder for typed field-to-field connections between nodes. |
+| `manifest` | Structured per-run log: which nodes fired, what they got, what they returned. |
+
+## Architecture
+
+- **Nodes** are frozen, single forward pass, locked output.
+- **Composition** is a static DAG declared in Python.
+- **Training** is 100% synthetic, offline.
+- **OOD** is a first-class type (Ok / OOD discriminated union).
+- **Every node ships with golden tests** (`pytest`).
+- **Every run emits a manifest.**
+
+## Wrapping external models
+
+External models (HuggingFace, hosted APIs, pure functions) become nodes through wrappers. They never get called directly.
+
+```python
+from snail.wrappers import ExternalLocalNode, HostedNode, DeterministicNode
+
+# Pin a local model to exact weights hash
+classify_layout = ExternalLocalNode(
+    name="classify_layout",
+    input_schema=InvoiceImage,
+    output_schema=LayoutClass,
+    distribution="rvl_cdip_subset",
+    call=lambda img: yolo_model.predict(img.path),
+    weight_pin="yolov8n@sha256:abc123...",
+)
+
+# Wrap a hosted API
+summarize = HostedNode(
+    name="summarize",
+    input_schema=InvoiceText,
+    output_schema=InvoiceSummary,
+    endpoint="anthropic://claude-sonnet-4-5",
+    prompt_template="Summarize: {text}",
+    api_key_env="ANTHROPIC_API_KEY",
+)
+
+# Or just a pure function
+validate_email = DeterministicNode(
+    name="validate_email",
+    input_schema=EmailField,
+    output_schema=EmailValidated,
+    fn=lambda x: x if "@" in x.value else None,
+    ood_on_none=True,
+)
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Golden tests live in `tests/golden/`. The lint rule (catches direct `import openai`, `import anthropic`, etc. outside wrappers) is enforced via the `snail.lint` module.
+
+## License
+
+Apache License 2.0. Copyright 2026 Tico Internet LLC.
+
+## Status
+
+v0.1.0 — alpha. The core primitives (`@node`, `Program`, `edge()`, wrappers, manifest, lint) are working. The training pipeline for producing `.snail` weights is not yet included — that ships in v0.2.0.

snail_dsl-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snail-dsl"
+version = "0.1.0"
+description = "Single Node Activated Inference Layer — a Python DSL for composing frozen neural primitives into typed dataflow programs."
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Tico Internet LLC"},
+]
+keywords = ["ai", "ml", "dsl", "frozen-models", "dataflow", "neural-networks", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "build>=0.10",
+    "twine>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lordxmen2k/SNAIL-DSL"
+Repository = "https://github.com/lordxmen2k/SNAIL-DSL"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

snail_dsl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snail_dsl-0.1.0/src/snail/__init__.py

@@ -0,0 +1,47 @@
+"""SNAIL — Single Node Activated Inference Layer.
+
+A Python DSL for composing frozen, single-pass neural primitives
+into statically-typed dataflow programs.
+
+Public API (import from `snail`):
+    node           — decorator that wraps a function as a frozen SNAIL node
+    NodeContext    — per-call context passed to node bodies
+    Program        — typed DAG container for nodes
+    edge           — builder for typed connections between nodes
+    NodeResult     — base class for all node output schemas
+    OODSignal      — out-of-distribution signal type
+    Manifest       — per-run audit log
+
+Subpackages:
+    snail.wrappers — ExternalLocalNode, HostedNode, DeterministicNode
+    snail.lint     — discipline check that catches direct model SDK imports
+    snail.types    — internal type definitions
+
+License: Apache 2.0. Copyright 2026 Tico Internet LLC.
+"""
+
+from snail.node import node, NodeContext, FrozenWeights
+from snail.program import Program, Edge, edge, NodeProxy, ProgramRunResult
+from snail.types.result import NodeResult
+from snail.types.ood import OODSignal
+from snail.manifest import Manifest, ManifestBuilder
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core
+    "node",
+    "NodeContext",
+    "FrozenWeights",
+    "Program",
+    "Edge",
+    "edge",
+    "NodeProxy",
+    "ProgramRunResult",
+    # types
+    "NodeResult",
+    "OODSignal",
+    # observability
+    "Manifest",
+    "ManifestBuilder",
+]

snail_dsl-0.1.0/src/snail/lint.py

@@ -0,0 +1,88 @@
+"""SNAIL lint rule — catches direct imports of model SDKs outside wrappers.
+
+If you import openai/anthropic/transformers/etc. at module level in a
+file that isn't a SNAIL wrapper, that's a violation. All model access
+must go through @node or one of the snail.wrappers factories.
+
+This is a discipline check, not a style preference. The lint module
+exposes a `check_source(path)` function for CI integration and a
+`FORBIDDEN_TOP_LEVEL_IMPORTS` set for users to extend.
+"""
+
+from __future__ import annotations
+import ast
+from pathlib import Path
+
+# These modules, if imported at module level outside snail.wrappers,
+# indicate someone is calling a model directly without going through @node.
+FORBIDDEN_TOP_LEVEL_IMPORTS: set[str] = {
+    "openai",
+    "anthropic",
+    "transformers",
+    "torch",            # torch at module level outside training scripts
+    "tensorflow",
+    "jax",
+    "flax",
+    "replicate",
+    "huggingface_hub",
+    "litellm",
+    "ollama",
+    "langchain",
+    "langgraph",
+    "crewai",
+}
+
+
+def check_source(path: str | Path) -> list[str]:
+    """Return a list of violation messages for the given Python file.
+
+    Empty list = clean.
+    """
+    p = Path(path)
+    if not p.exists():
+        return [f"file not found: {p}"]
+
+    # Don't lint the wrappers module itself — that's where model SDKs are
+    # allowed to be imported.
+    if "snail/wrappers" in str(p) or "snail\\wrappers" in str(p):
+        return []
+    # Don't lint the lint module itself.
+    if "snail/lint" in str(p):
+        return []
+
+    try:
+        tree = ast.parse(p.read_text())
+    except SyntaxError as e:
+        return [f"SyntaxError: {e}"]
+
+    violations: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                top = alias.name.split(".")[0]
+                if top in FORBIDDEN_TOP_LEVEL_IMPORTS:
+                    violations.append(
+                        f"{p}:{node.lineno}: direct import of {alias.name!r}. "
+                        "Model SDKs must go through @node or snail.wrappers."
+                    )
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                top = node.module.split(".")[0]
+                if top in FORBIDDEN_TOP_LEVEL_IMPORTS:
+                    violations.append(
+                        f"{p}:{node.lineno}: direct import from {node.module!r}. "
+                        "Model SDKs must go through @node or snail.wrappers."
+                    )
+    return violations
+
+
+def check_directory(root: str | Path, exclude_dirs: set[str] | None = None) -> list[str]:
+    """Walk a directory tree and lint every .py file. Returns all violations."""
+    exclude = exclude_dirs or {".venv", "venv", "build", "dist", "__pycache__", ".git"}
+    root = Path(root)
+    all_violations: list[str] = []
+    for p in root.rglob("*.py"):
+        if any(part in exclude for part in p.parts):
+            continue
+        all_violations.extend(check_source(p))
+    return all_violations

snail_dsl-0.1.0/src/snail/manifest.py

@@ -0,0 +1,108 @@
+"""Run manifests — structured per-run log of what fired, when, and what it returned.
+
+Every Program.run() emits a manifest. Manifests are JSON-serializable.
+They are the audit trail for any SNAIL program — show them to compliance,
+to your CEO, to the user who asked why their refund took 2 seconds.
+"""
+
+from __future__ import annotations
+import json
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from typing import Any
+
+
+@dataclass
+class ManifestNodeEvent:
+    node_name: str
+    variant: str  # "ok" or "ood"
+    latency_ms: float
+    confidence: float | None = None
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class ManifestErrorEvent:
+    node_name: str
+    error: str
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class Manifest:
+    program_name: str
+    run_id: str
+    started_at: float
+    ended_at: float | None
+    total_duration_ms: float
+    node_events: list[ManifestNodeEvent]
+    errors: list[ManifestErrorEvent]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "program_name": self.program_name,
+            "run_id": self.run_id,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+            "total_duration_ms": self.total_duration_ms,
+            "node_events": [asdict(e) for e in self.node_events],
+            "errors": [asdict(e) for e in self.errors],
+        }
+
+    def to_json(self, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+
+class ManifestBuilder:
+    """Accumulates events during a single Program.run() and emits a Manifest."""
+
+    def __init__(self, program_name: str, run_id: str | None = None):
+        self.program_name = program_name
+        self.run_id = run_id or str(uuid.uuid4())
+        self._started_at: float | None = None
+        self._ended_at: float | None = None
+        self._node_events: list[ManifestNodeEvent] = []
+        self._errors: list[ManifestErrorEvent] = []
+
+    def record_start(self) -> None:
+        self._started_at = time.time()
+
+    def record_end(self) -> None:
+        self._ended_at = time.time()
+
+    def record_node(
+        self,
+        *,
+        node_name: str,
+        variant: str,
+        latency_ms: float,
+        confidence: float | None = None,
+    ) -> None:
+        self._node_events.append(
+            ManifestNodeEvent(
+                node_name=node_name,
+                variant=variant,
+                latency_ms=latency_ms,
+                confidence=confidence,
+            )
+        )
+
+    def record_error(self, *, node_name: str, error: str) -> None:
+        self._errors.append(
+            ManifestErrorEvent(node_name=node_name, error=error)
+        )
+
+    def build(self) -> Manifest:
+        if self._started_at is None:
+            raise RuntimeError("ManifestBuilder.build() called before record_start()")
+        ended = self._ended_at if self._ended_at is not None else time.time()
+        return Manifest(
+            program_name=self.program_name,
+            run_id=self.run_id,
+            started_at=self._started_at,
+            ended_at=self._ended_at,
+            total_duration_ms=(ended - self._started_at) * 1000.0,
+            node_events=list(self._node_events),
+            errors=list(self._errors),
+        )