nemoir-runtime 0.1.0__tar.gz

nemoir_runtime-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv
+.pytest_cache
+.ruff_cache
+*.egg-info
+__pycache__

nemoir_runtime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NemoIR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nemoir_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: nemoir-runtime
+Version: 0.1.0
+Summary: Python runtime core for NemoIR — execute compiled agent workflows as structured state machines with tool orchestration, policy enforcement, model-backed stage execution, and live event streaming.
+Project-URL: Repository, https://github.com/nemoir
+Author: NemoIR Contributors
+License: MIT License
+        
+        Copyright (c) 2025 NemoIR
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,ai,compiler,llm,nemo,runtime,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: litellm>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# NemoIR Runtime
+
+Python runtime core for [NemoIR](https://github.com/nemoir) — an LLVM-inspired compiler stack for agentic workflows.
+
+Executes compiled agent workflows as structured state machines with tool orchestration, policy enforcement, model-backed stage execution (via [LiteLLM](https://github.com/BerriAI/litellm)), and live event streaming.
+
+## Features
+
+- **Workflow runtime** — state-machine execution with stage ordering, read/write resolution, transition selection, and run limits.
+- **Tool framework** — capability-based tool registration, catalog-driven parameter validation, and policy-gated invocation (`fs.read`, `fs.write`, `user.confirm`, `os.shell`, `user.elicit`).
+- **Policy engine** — deny and before-policies with expression evaluation (e.g., path containment guards).
+- **Model integration** — `ModelStageExecutor` with LiteLLM adapter, structured output enforcement, tool-call loop, `ModelRouter` for per-stage model routing, and optional streaming via `ModelStreamingAdapter`.
+- **Live event streaming** — `WorkflowRuntime.stream()` / generated `Agent.stream()` async iterator emitting `WorkflowEvent` values (run lifecycle, model deltas, tool calls, policy decisions) for UIs, debugging, and observability.
+- **Compiler backend target** — generated workflow-specific Python packages consume this runtime; see `nemoir-backend-python` in the main NemoIR repo.
+
+## Install
+
+```bash
+pip install nemoir-runtime
+```
+
+## Quick start
+
+```python
+import asyncio
+from pathlib import Path
+from nemoir_runtime import WorkflowRuntime, WorkflowManifest, Tool, ToolContext, ToolRegistry
+
+# Define tools
+async def read_file(*, path: Path, ctx: ToolContext) -> str:
+    return Path(path).read_text()
+
+tools = ToolRegistry([
+    Tool(name="read_file", capability="fs.read", description="Read a file",
+         input_schema={"path": Path}, handler=read_file),
+])
+
+# Load a manifest (typically generated by the NemoIR compiler)
+manifest = WorkflowManifest(...)
+
+runtime = WorkflowRuntime(manifest=manifest, tools=tools, stage_executor=my_executor)
+result = await runtime.run({"task": "analyze code"})
+print(result.output)
+```
+
+See the [NemoIR project](https://github.com/nemoir) for the full compiler workflow (DSL → IR → generated package).
+
+## Requirements
+
+- Python ≥ 3.11
+- LiteLLM ≥ 1.0.0 (for `LiteLLMModelAdapter`; custom `ModelAdapter` implementations can avoid this dependency)

nemoir_runtime-0.1.0/README.md

@@ -0,0 +1,51 @@
+# NemoIR Runtime
+
+Python runtime core for [NemoIR](https://github.com/nemoir) — an LLVM-inspired compiler stack for agentic workflows.
+
+Executes compiled agent workflows as structured state machines with tool orchestration, policy enforcement, model-backed stage execution (via [LiteLLM](https://github.com/BerriAI/litellm)), and live event streaming.
+
+## Features
+
+- **Workflow runtime** — state-machine execution with stage ordering, read/write resolution, transition selection, and run limits.
+- **Tool framework** — capability-based tool registration, catalog-driven parameter validation, and policy-gated invocation (`fs.read`, `fs.write`, `user.confirm`, `os.shell`, `user.elicit`).
+- **Policy engine** — deny and before-policies with expression evaluation (e.g., path containment guards).
+- **Model integration** — `ModelStageExecutor` with LiteLLM adapter, structured output enforcement, tool-call loop, `ModelRouter` for per-stage model routing, and optional streaming via `ModelStreamingAdapter`.
+- **Live event streaming** — `WorkflowRuntime.stream()` / generated `Agent.stream()` async iterator emitting `WorkflowEvent` values (run lifecycle, model deltas, tool calls, policy decisions) for UIs, debugging, and observability.
+- **Compiler backend target** — generated workflow-specific Python packages consume this runtime; see `nemoir-backend-python` in the main NemoIR repo.
+
+## Install
+
+```bash
+pip install nemoir-runtime
+```
+
+## Quick start
+
+```python
+import asyncio
+from pathlib import Path
+from nemoir_runtime import WorkflowRuntime, WorkflowManifest, Tool, ToolContext, ToolRegistry
+
+# Define tools
+async def read_file(*, path: Path, ctx: ToolContext) -> str:
+    return Path(path).read_text()
+
+tools = ToolRegistry([
+    Tool(name="read_file", capability="fs.read", description="Read a file",
+         input_schema={"path": Path}, handler=read_file),
+])
+
+# Load a manifest (typically generated by the NemoIR compiler)
+manifest = WorkflowManifest(...)
+
+runtime = WorkflowRuntime(manifest=manifest, tools=tools, stage_executor=my_executor)
+result = await runtime.run({"task": "analyze code"})
+print(result.output)
+```
+
+See the [NemoIR project](https://github.com/nemoir) for the full compiler workflow (DSL → IR → generated package).
+
+## Requirements
+
+- Python ≥ 3.11
+- LiteLLM ≥ 1.0.0 (for `LiteLLMModelAdapter`; custom `ModelAdapter` implementations can avoid this dependency)

nemoir_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nemoir-runtime"
+version = "0.1.0"
+description = "Python runtime core for NemoIR — execute compiled agent workflows as structured state machines with tool orchestration, policy enforcement, model-backed stage execution, and live event streaming."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "NemoIR Contributors" },
+]
+keywords = ["nemo", "agent", "workflow", "llm", "compiler", "runtime", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+urls = { Repository = "https://github.com/nemoir" }
+requires-python = ">=3.11"
+dependencies = [
+    "litellm>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pyright>=1.1.0",
+    "ruff>=0.1.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.pyright]
+typeCheckingMode = "strict"
+venv = ".venv"
+venvPath = "."
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D",
+    "COM812",
+    "TRY003",
+    "ANN401",
+    "PLR0913",
+    "BLE001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "ARG001",
+    "S108",
+    "PLR2004",
+    "PT011",
+    "B017",
+    "ANN001",
+]
+"tests/test_events.py" = ["PERF401"]
+"tests/test_models.py" = ["PERF401"]
+"tests/test_generated_package.py" = ["PERF401"]

nemoir_runtime-0.1.0/src/nemoir_runtime/__init__.py

@@ -0,0 +1,136 @@
+from nemoir_runtime.capabilities import (
+    CAPABILITY_CATALOG,
+    CapabilityParam,
+    CapabilityParamType,
+    CapabilitySpec,
+    get_capability,
+    required_param_names,
+)
+from nemoir_runtime.errors import (
+    DataUnavailableError,
+    MaxStepsExceededError,
+    MissingCapabilityError,
+    ModelOutputValidationError,
+    ModelProviderError,
+    NemoIRRuntimeError,
+    NoTransitionMatchedError,
+    PolicyDeniedError,
+    PolicyEvaluationError,
+    StageOutputValidationError,
+    ToolInvocationError,
+    ToolValidationError,
+    WorkflowTimeoutError,
+    WorkflowValidationError,
+)
+from nemoir_runtime.events import (
+    WorkflowEvent,
+    WorkflowEventChannel,
+    WorkflowEventEmitter,
+    WorkflowEventKind,
+    WorkflowEventSink,
+)
+from nemoir_runtime.models import (
+    LiteLLMModelAdapter,
+    ModelAdapter,
+    ModelRequest,
+    ModelResponse,
+    ModelRouter,
+    ModelSpec,
+    ModelStageExecutor,
+    ModelStreamChunk,
+    ModelStreamingAdapter,
+    ModelToolCall,
+    supports_streaming,
+)
+from nemoir_runtime.runtime import (
+    ExprSpec,
+    GuardSpec,
+    InputSpec,
+    PolicySpec,
+    ReadSpec,
+    RefSpec,
+    RequiredCapabilitySpec,
+    RunOptions,
+    StageContext,
+    StageExecutor,
+    StageSpec,
+    TransitionSpec,
+    TriggerSpec,
+    WorkflowManifest,
+    WorkflowResult,
+    WorkflowRuntime,
+    WorkflowState,
+    WriteSpec,
+)
+from nemoir_runtime.tools import (
+    Tool,
+    ToolContext,
+    ToolRegistry,
+    tool,
+)
+
+__all__ = [
+    "CAPABILITY_CATALOG",
+    "CapabilityParam",
+    "CapabilityParamType",
+    "CapabilitySpec",
+    "DataUnavailableError",
+    "ExprSpec",
+    "GuardSpec",
+    "InputSpec",
+    "LiteLLMModelAdapter",
+    "MaxStepsExceededError",
+    "MissingCapabilityError",
+    "ModelAdapter",
+    "ModelOutputValidationError",
+    "ModelProviderError",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelRouter",
+    "ModelSpec",
+    "ModelStageExecutor",
+    "ModelStreamChunk",
+    "ModelStreamingAdapter",
+    "ModelToolCall",
+    "NemoIRRuntimeError",
+    "NoTransitionMatchedError",
+    "PolicyDeniedError",
+    "PolicyEvaluationError",
+    "PolicySpec",
+    "ReadSpec",
+    "RefSpec",
+    "RequiredCapabilitySpec",
+    "RunOptions",
+    "StageContext",
+    "StageExecutor",
+    "StageOutputValidationError",
+    "StageSpec",
+    "Tool",
+    "ToolContext",
+    "ToolInvocationError",
+    "ToolRegistry",
+    "ToolValidationError",
+    "TransitionSpec",
+    "TriggerSpec",
+    "WorkflowManifest",
+    "WorkflowResult",
+    "WorkflowRuntime",
+    "WorkflowState",
+    "WorkflowTimeoutError",
+    "WorkflowValidationError",
+    "WriteSpec",
+    "get_capability",
+    "required_param_names",
+    "supports_streaming",
+    "tool",
+]
+
+# Extended with Phase 5 event primitives (re-exported for convenience).
+# Advanced users may import directly from nemoir_runtime.events.
+__all__ += [
+    "WorkflowEvent",
+    "WorkflowEventChannel",
+    "WorkflowEventEmitter",
+    "WorkflowEventKind",
+    "WorkflowEventSink",
+]

nemoir_runtime-0.1.0/src/nemoir_runtime/capabilities.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+class CapabilityParamType(Enum):
+    STRING = "string"
+    PATH = "path"
+    BOOL = "bool"
+
+
+@dataclass(frozen=True)
+class CapabilityParam:
+    name: str
+    type: CapabilityParamType
+
+
+@dataclass(frozen=True)
+class CapabilitySpec:
+    name: str
+    required_params: tuple[CapabilityParam, ...]
+
+    def has_required_param(self, name: str) -> bool:
+        return any(param.name == name for param in self.required_params)
+
+
+CAPABILITY_CATALOG: Mapping[str, CapabilitySpec] = MappingProxyType(
+    {
+        "fs.read": CapabilitySpec(
+            name="fs.read",
+            required_params=(CapabilityParam("path", CapabilityParamType.PATH),),
+        ),
+        "fs.write": CapabilitySpec(
+            name="fs.write",
+            required_params=(
+                CapabilityParam("path", CapabilityParamType.PATH),
+                CapabilityParam("content", CapabilityParamType.STRING),
+            ),
+        ),
+        "os.shell": CapabilitySpec(
+            name="os.shell",
+            required_params=(CapabilityParam("command", CapabilityParamType.STRING),),
+        ),
+        "user.elicit": CapabilitySpec(
+            name="user.elicit",
+            required_params=(CapabilityParam("question", CapabilityParamType.STRING),),
+        ),
+        "user.confirm": CapabilitySpec(
+            name="user.confirm",
+            required_params=(CapabilityParam("message", CapabilityParamType.STRING),),
+        ),
+    },
+)
+
+
+def get_capability(name: str) -> CapabilitySpec | None:
+    return CAPABILITY_CATALOG.get(name)
+
+
+def required_param_names(name: str) -> frozenset[str]:
+    spec = get_capability(name)
+    if spec is None:
+        return frozenset()
+    return frozenset(param.name for param in spec.required_params)

nemoir_runtime-0.1.0/src/nemoir_runtime/errors.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+
+class NemoIRRuntimeError(Exception):
+    pass
+
+
+class ToolValidationError(NemoIRRuntimeError):
+    pass
+
+
+class MissingCapabilityError(NemoIRRuntimeError):
+    pass
+
+
+class ToolInvocationError(NemoIRRuntimeError):
+    pass
+
+
+class PolicyDeniedError(NemoIRRuntimeError):
+    pass
+
+
+class PolicyEvaluationError(NemoIRRuntimeError):
+    pass
+
+
+class StageOutputValidationError(NemoIRRuntimeError):
+    pass
+
+
+class DataUnavailableError(NemoIRRuntimeError):
+    pass
+
+
+class NoTransitionMatchedError(NemoIRRuntimeError):
+    pass
+
+
+class MaxStepsExceededError(NemoIRRuntimeError):
+    pass
+
+
+class WorkflowTimeoutError(NemoIRRuntimeError):
+    pass
+
+
+class WorkflowValidationError(NemoIRRuntimeError):
+    pass
+
+
+class ModelProviderError(NemoIRRuntimeError):
+    pass
+
+
+class ModelOutputValidationError(NemoIRRuntimeError):
+    pass

nemoir_runtime-0.1.0/src/nemoir_runtime/events.py

@@ -0,0 +1,105 @@
+"""Workflow event primitives for live streaming, UI observation, and debugging.
+
+Defines the event types, channels, emitter, and sink that the runtime uses
+to expose stage lifecycle, model deltas, tool calls, policy decisions, and
+run-level outcomes as an observable async stream.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+WorkflowEventKind = Literal[
+    "run_started",
+    "stage_started",
+    "model_delta",
+    "model_completed",
+    "tool_call_started",
+    "tool_call_completed",
+    "tool_call_failed",
+    "policy_checked",
+    "policy_denied",
+    "transition_selected",
+    "stage_completed",
+    "run_completed",
+    "run_failed",
+]
+
+WorkflowEventChannel = Literal[
+    "assistant",
+    "progress",
+    "reasoning_summary",
+    "debug",
+]
+
+
+@dataclass(frozen=True)
+class WorkflowEvent:
+    kind: WorkflowEventKind
+    run_id: str
+    sequence: int
+    timestamp: datetime
+    stage_id: str | None = None
+    channel: WorkflowEventChannel | None = None
+    text: str | None = None
+    capability: str | None = None
+    tool_name: str | None = None
+    args: Mapping[str, Any] | None = None
+    output: Mapping[str, Any] | None = None
+    result: Any = None
+    error: str | None = None
+    transition_to: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)  # type: ignore[reportUnknownVariableType]
+
+
+WorkflowEventSink = Callable[[WorkflowEvent], Awaitable[None]]
+
+
+class WorkflowEventEmitter:
+    """Per-run event emitter with monotonic sequencing.
+
+    The emitter is cheap when the sink is ``None``: ``emit()`` still
+    constructs and returns the event (for tests), but no I/O happens.
+    """
+
+    def __init__(self, *, run_id: str, sink: WorkflowEventSink | None = None) -> None:
+        self._run_id = run_id
+        self._sink = sink
+        self._seq = 0
+
+    @property
+    def run_id(self) -> str:
+        return self._run_id
+
+    @property
+    def sequence(self) -> int:
+        return self._seq
+
+    @property
+    def has_sink(self) -> bool:
+        """True when an actual consumer is attached.
+
+        Use this to decide whether to activate provider-side streaming:
+        only stream when someone is listening.
+        """
+        return self._sink is not None
+
+    async def emit(
+        self,
+        kind: WorkflowEventKind,
+        **kwargs: Any,
+    ) -> WorkflowEvent:
+        self._seq += 1
+        event = WorkflowEvent(
+            kind=kind,
+            run_id=self._run_id,
+            sequence=self._seq,
+            timestamp=datetime.now(tz=UTC),
+            **kwargs,
+        )
+        if self._sink is not None:
+            await self._sink(event)
+        return event