namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/runtime/ai/providers/_shared/parse.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import json
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def ensure_text_output(provider_name: str, text: object) -> str:
+    if isinstance(text, str) and text.strip() != "":
+        return text
+    raise Namel3ssError(f"Provider '{provider_name}' returned an invalid response")
+
+
+def json_loads_or_error(provider_name: str, raw: bytes) -> dict:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except Exception as err:  # json.JSONDecodeError or UnicodeError
+        raise Namel3ssError(f"Provider '{provider_name}' returned an invalid response") from err

namel3ss/runtime/ai/providers/anthropic.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from namel3ss.config.model import AnthropicConfig
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.http.client import post_json
+from namel3ss.runtime.ai.provider import AIProvider, AIResponse
+from namel3ss.runtime.ai.providers._shared.errors import require_env
+from namel3ss.runtime.ai.providers._shared.parse import ensure_text_output
+
+ANTHROPIC_VERSION = "2023-06-01"
+
+
+class AnthropicProvider(AIProvider):
+    def __init__(self, *, api_key: str | None, timeout_seconds: int = 30):
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+
+    @classmethod
+    def from_config(cls, config: AnthropicConfig) -> "AnthropicProvider":
+        return cls(api_key=config.api_key)
+
+    def ask(self, *, model: str, system_prompt: str | None, user_input: str, tools=None, memory=None, tool_results=None):
+        key = require_env("anthropic", "NAMEL3SS_ANTHROPIC_API_KEY", self.api_key)
+        url = "https://api.anthropic.com/v1/messages"
+        payload = {"model": model, "messages": [{"role": "user", "content": user_input}]}
+        if system_prompt:
+            payload["system"] = system_prompt
+        headers = {
+            "x-api-key": key,
+            "anthropic-version": ANTHROPIC_VERSION,
+            "Content-Type": "application/json",
+        }
+        try:
+            result = post_json(
+                url=url,
+                headers=headers,
+                payload=payload,
+                timeout_seconds=self.timeout_seconds,
+                provider_name="anthropic",
+            )
+        except Namel3ssError:
+            raise
+        text = _extract_text(result)
+        return AIResponse(output=ensure_text_output("anthropic", text))
+
+
+def _extract_text(result: dict) -> str | None:
+    content = result.get("content")
+    if isinstance(content, list) and content:
+        first = content[0]
+        if isinstance(first, dict):
+            text = first.get("text")
+            if isinstance(text, str):
+                return text
+    return None

namel3ss/runtime/ai/providers/gemini.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from namel3ss.config.model import GeminiConfig
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.http.client import post_json
+from namel3ss.runtime.ai.provider import AIProvider, AIResponse
+from namel3ss.runtime.ai.providers._shared.errors import require_env
+from namel3ss.runtime.ai.providers._shared.parse import ensure_text_output
+
+
+class GeminiProvider(AIProvider):
+    def __init__(self, *, api_key: str | None, timeout_seconds: int = 30):
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+
+    @classmethod
+    def from_config(cls, config: GeminiConfig) -> "GeminiProvider":
+        return cls(api_key=config.api_key)
+
+    def ask(self, *, model: str, system_prompt: str | None, user_input: str, tools=None, memory=None, tool_results=None):
+        key = require_env("gemini", "NAMEL3SS_GEMINI_API_KEY", self.api_key)
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={key}"
+        text = user_input if not system_prompt else f"{system_prompt}\n{user_input}"
+        payload = {"contents": [{"role": "user", "parts": [{"text": text}]}]}
+        headers = {"Content-Type": "application/json"}
+        try:
+            result = post_json(
+                url=url,
+                headers=headers,
+                payload=payload,
+                timeout_seconds=self.timeout_seconds,
+                provider_name="gemini",
+            )
+        except Namel3ssError:
+            raise
+        text_out = _extract_text(result)
+        return AIResponse(output=ensure_text_output("gemini", text_out))
+
+
+def _extract_text(result: dict) -> str | None:
+    candidates = result.get("candidates")
+    if isinstance(candidates, list) and candidates:
+        content = candidates[0].get("content") if isinstance(candidates[0], dict) else None
+        if isinstance(content, dict):
+            parts = content.get("parts")
+            if isinstance(parts, list):
+                texts = [part.get("text") for part in parts if isinstance(part, dict) and isinstance(part.get("text"), str)]
+                if texts:
+                    return "\n".join(texts)
+    return None

namel3ss/runtime/ai/providers/mistral.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from namel3ss.config.model import MistralConfig
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.http.client import post_json
+from namel3ss.runtime.ai.provider import AIProvider, AIResponse
+from namel3ss.runtime.ai.providers._shared.errors import require_env
+from namel3ss.runtime.ai.providers._shared.parse import ensure_text_output
+
+
+class MistralProvider(AIProvider):
+    def __init__(self, *, api_key: str | None, timeout_seconds: int = 30):
+        self.api_key = api_key
+        self.timeout_seconds = timeout_seconds
+
+    @classmethod
+    def from_config(cls, config: MistralConfig) -> "MistralProvider":
+        return cls(api_key=config.api_key)
+
+    def ask(self, *, model: str, system_prompt: str | None, user_input: str, tools=None, memory=None, tool_results=None):
+        key = require_env("mistral", "NAMEL3SS_MISTRAL_API_KEY", self.api_key)
+        url = "https://api.mistral.ai/v1/chat/completions"
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": user_input})
+        payload = {"model": model, "messages": messages}
+        headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+        try:
+            result = post_json(
+                url=url,
+                headers=headers,
+                payload=payload,
+                timeout_seconds=self.timeout_seconds,
+                provider_name="mistral",
+            )
+        except Namel3ssError:
+            raise
+        text = _extract_text(result)
+        return AIResponse(output=ensure_text_output("mistral", text))
+
+
+def _extract_text(result: dict) -> str | None:
+    choices = result.get("choices")
+    if isinstance(choices, list) and choices:
+        message = choices[0].get("message") if isinstance(choices[0], dict) else None
+        if isinstance(message, dict):
+            content = message.get("content")
+            if isinstance(content, str):
+                return content
+    return None

namel3ss/runtime/ai/providers/mock.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from namel3ss.runtime.ai.provider import AIProvider, AIResponse, AIToolCallResponse
+
+
+class MockProvider(AIProvider):
+    def __init__(self, tool_call_sequence=None):
+        self.tool_call_sequence = tool_call_sequence or []
+        self.call_index = 0
+
+    def ask(self, *, model: str, system_prompt: str | None, user_input: str, tools=None, memory=None, tool_results=None):
+        if self.call_index < len(self.tool_call_sequence):
+            resp = self.tool_call_sequence[self.call_index]
+            self.call_index += 1
+            if isinstance(resp, AIToolCallResponse):
+                return resp
+        prefix = f"[{model}]"
+        mem_note = ""
+        if memory:
+            mem_note = f" | mem:st={len(memory.get('short_term', []))}"
+        if system_prompt:
+            return AIResponse(output=str(f"{prefix} {system_prompt} :: {user_input}{mem_note}"))
+        return AIResponse(output=str(f"{prefix} {user_input}{mem_note}"))

namel3ss/runtime/ai/providers/ollama.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.http.client import post_json
+from namel3ss.runtime.ai.provider import AIProvider, AIResponse
+from namel3ss.runtime.ai.providers._shared.errors import map_http_error
+from namel3ss.runtime.ai.providers._shared.parse import ensure_text_output
+
+
+class OllamaProvider(AIProvider):
+    def __init__(self, *, host: str, timeout_seconds: int = 30):
+        self.host = host.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+
+    def ask(self, *, model: str, system_prompt: str | None, user_input: str, tools=None, memory=None, tool_results=None):
+        url = f"{self.host}/api/chat"
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": user_input})
+        payload = {"model": model, "messages": messages}
+        try:
+            result = post_json(url=url, headers={"Content-Type": "application/json"}, payload=payload, timeout_seconds=self.timeout_seconds, provider_name="ollama")
+        except Namel3ssError:
+            raise
+        except Exception as err:
+            raise map_http_error("ollama", err) from err
+        content = _extract_content(result)
+        return AIResponse(output=ensure_text_output("ollama", content))
+
+
+def _extract_content(payload: dict) -> str | None:
+    if "message" in payload and isinstance(payload["message"], dict):
+        content = payload["message"].get("content")
+        if isinstance(content, str):
+            return content
+    if "response" in payload and isinstance(payload["response"], str):
+        return payload["response"]
+    return None

namel3ss/runtime/ai/providers/openai.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from namel3ss.config.model import OpenAIConfig
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.http.client import post_json
+from namel3ss.runtime.ai.provider import AIProvider, AIResponse
+from namel3ss.runtime.ai.providers._shared.errors import require_env
+from namel3ss.runtime.ai.providers._shared.parse import ensure_text_output
+
+
+class OpenAIProvider(AIProvider):
+    def __init__(self, *, api_key: str | None, base_url: str = "https://api.openai.com", timeout_seconds: int = 30):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+
+    @classmethod
+    def from_config(cls, config: OpenAIConfig) -> "OpenAIProvider":
+        return cls(api_key=config.api_key, base_url=config.base_url)
+
+    def ask(self, *, model: str, system_prompt: str | None, user_input: str, tools=None, memory=None, tool_results=None):
+        key = require_env("openai", "NAMEL3SS_OPENAI_API_KEY", self.api_key)
+        url = f"{self.base_url}/v1/responses"
+        payload = {"model": model, "input": user_input}
+        if system_prompt:
+            payload["system"] = system_prompt
+        headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+        try:
+            result = post_json(
+                url=url,
+                headers=headers,
+                payload=payload,
+                timeout_seconds=self.timeout_seconds,
+                provider_name="openai",
+            )
+        except Namel3ssError:
+            raise
+        text = _extract_text(result)
+        return AIResponse(output=ensure_text_output("openai", text))
+
+
+def _extract_text(result: dict) -> str | None:
+    if isinstance(result.get("output_text"), str):
+        return result["output_text"]
+    output = result.get("output")
+    if isinstance(output, list) and output:
+        content = output[0].get("content") if isinstance(output[0], dict) else None
+        if isinstance(content, list) and content:
+            text = content[0].get("text")
+            if isinstance(text, str):
+                return text
+    message = result.get("message")
+    if isinstance(message, dict) and isinstance(message.get("content"), str):
+        return message["content"]
+    return None

namel3ss/runtime/ai/providers/registry.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from namel3ss.config import load_config
+from namel3ss.config.model import AppConfig
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.provider import AIProvider
+from namel3ss.runtime.ai.providers.mock import MockProvider
+from namel3ss.runtime.ai.providers.ollama import OllamaProvider
+from namel3ss.runtime.ai.providers.openai import OpenAIProvider
+from namel3ss.runtime.ai.providers.anthropic import AnthropicProvider
+from namel3ss.runtime.ai.providers.gemini import GeminiProvider
+from namel3ss.runtime.ai.providers.mistral import MistralProvider
+
+
+_FACTORIES = {
+    "mock": lambda config: MockProvider(),
+    "ollama": lambda config: OllamaProvider(
+        host=config.ollama.host,
+        timeout_seconds=config.ollama.timeout_seconds,
+    ),
+    "openai": lambda config: OpenAIProvider.from_config(config.openai),
+    "anthropic": lambda config: AnthropicProvider.from_config(config.anthropic),
+    "gemini": lambda config: GeminiProvider.from_config(config.gemini),
+    "mistral": lambda config: MistralProvider.from_config(config.mistral),
+}
+
+
+def is_supported_provider(name: str) -> bool:
+    return name.lower() in _FACTORIES
+
+
+def get_provider(name: str, config: AppConfig | None = None) -> AIProvider:
+    normalized = name.lower()
+    if normalized not in _FACTORIES:
+        available = ", ".join(sorted(_FACTORIES))
+        raise Namel3ssError(f"Unknown AI provider '{name}'. Available: {available}")
+    cfg = config or load_config()
+    return _FACTORIES[normalized](cfg)

namel3ss/runtime/ai/trace.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AITrace:
+    ai_name: str
+    agent_name: Optional[str]
+    ai_profile_name: Optional[str]
+    model: str
+    system_prompt: Optional[str]
+    input: str
+    output: str
+    memory: dict
+    tool_calls: list
+    tool_results: list

namel3ss/runtime/executor/__init__.py

@@ -0,0 +1,3 @@
+from namel3ss.runtime.executor.api import Executor, ExecutionResult, execute_flow, execute_program_flow
+
+__all__ = ["Executor", "ExecutionResult", "execute_flow", "execute_program_flow"]

namel3ss/runtime/executor/agents.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.ai.trace import AITrace
+from namel3ss.runtime.executor.ai_runner import run_ai_with_tools
+from namel3ss.runtime.executor.context import ExecutionContext
+from namel3ss.runtime.executor.expr_eval import evaluate_expression
+
+
+def execute_run_agent(ctx: ExecutionContext, stmt: ir.RunAgentStmt) -> None:
+    output, trace = run_agent_call(ctx, stmt.agent_name, stmt.input_expr, stmt.line, stmt.column)
+    ctx.traces.append(trace)
+    if stmt.target in ctx.constants:
+        raise Namel3ssError(f"Cannot assign to constant '{stmt.target}'", line=stmt.line, column=stmt.column)
+    ctx.locals[stmt.target] = output
+    ctx.last_value = output
+
+
+def execute_run_agents_parallel(ctx: ExecutionContext, stmt: ir.RunAgentsParallelStmt) -> None:
+    if len(stmt.entries) > 3:
+        raise Namel3ssError("Parallel agent limit exceeded")
+    results: list[str] = []
+    child_traces: list[dict] = []
+    for entry in stmt.entries:
+        try:
+            output, trace = run_agent_call(ctx, entry.agent_name, entry.input_expr, entry.line, entry.column)
+        except Namel3ssError as err:
+            raise Namel3ssError(f"Agent '{entry.agent_name}' failed: {err}", line=entry.line, column=entry.column) from err
+        results.append(output)
+        child_traces.append(_trace_to_dict(trace))
+    ctx.locals[stmt.target] = results
+    ctx.last_value = results
+    ctx.traces.append({"type": "parallel_agents", "target": stmt.target, "agents": child_traces})
+
+
+def run_agent_call(ctx: ExecutionContext, agent_name: str, input_expr, line: int | None, column: int | None):
+    ctx.agent_calls += 1
+    if ctx.agent_calls > 5:
+        raise Namel3ssError("Agent call limit exceeded in flow")
+    if agent_name not in ctx.agents:
+        raise Namel3ssError(f"Unknown agent '{agent_name}'", line=line, column=column)
+    agent = ctx.agents[agent_name]
+    ai_profile = ctx.ai_profiles.get(agent.ai_name)
+    if ai_profile is None:
+        raise Namel3ssError(f"Agent '{agent.name}' references unknown AI '{agent.ai_name}'", line=line, column=column)
+    user_input = evaluate_expression(ctx, input_expr)
+    if not isinstance(user_input, str):
+        raise Namel3ssError("Agent input must be a string", line=line, column=column)
+    profile_override = ir.AIDecl(
+        name=ai_profile.name,
+        model=ai_profile.model,
+        provider=ai_profile.provider,
+        system_prompt=agent.system_prompt or ai_profile.system_prompt,
+        exposed_tools=list(ai_profile.exposed_tools),
+        memory=ai_profile.memory,
+        line=ai_profile.line,
+        column=ai_profile.column,
+    )
+    memory_context = ctx.memory_manager.recall_context(profile_override, user_input, ctx.state)
+    tool_events: list[dict] = []
+    response_output = run_ai_with_tools(ctx, profile_override, user_input, memory_context, tool_events)
+    trace = AITrace(
+        ai_name=profile_override.name,
+        ai_profile_name=profile_override.name,
+        agent_name=agent.name,
+        model=profile_override.model,
+        system_prompt=profile_override.system_prompt,
+        input=user_input,
+        output=response_output,
+        memory=memory_context,
+        tool_calls=[e for e in tool_events if e.get("type") == "call"],
+        tool_results=[e for e in tool_events if e.get("type") == "result"],
+    )
+    ctx.memory_manager.record_interaction(profile_override, ctx.state, user_input, response_output, tool_events)
+    return response_output, trace
+
+
+def _trace_to_dict(trace: AITrace) -> dict:
+    return {
+        "ai_name": trace.ai_name,
+        "ai_profile_name": trace.ai_profile_name,
+        "agent_name": trace.agent_name,
+        "model": trace.model,
+        "system_prompt": trace.system_prompt,
+        "input": trace.input,
+        "output": trace.output,
+        "memory": trace.memory,
+        "tool_calls": trace.tool_calls,
+        "tool_results": trace.tool_results,
+    }

namel3ss/runtime/executor/ai_runner.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.ai.provider import AIToolCallResponse
+from namel3ss.runtime.ai.providers.registry import get_provider
+from namel3ss.runtime.ai.trace import AITrace
+from namel3ss.runtime.executor.context import ExecutionContext
+from namel3ss.runtime.executor.expr_eval import evaluate_expression
+from namel3ss.runtime.tools.registry import execute_tool
+
+
+def execute_ask_ai(ctx: ExecutionContext, expr: ir.AskAIStmt) -> str:
+    if expr.ai_name not in ctx.ai_profiles:
+        raise Namel3ssError(
+            f"Unknown AI '{expr.ai_name}'",
+            line=expr.line,
+            column=expr.column,
+        )
+    profile = ctx.ai_profiles[expr.ai_name]
+    user_input = evaluate_expression(ctx, expr.input_expr)
+    if not isinstance(user_input, str):
+        raise Namel3ssError("AI input must be a string", line=expr.line, column=expr.column)
+    memory_context = ctx.memory_manager.recall_context(profile, user_input, ctx.state)
+    tool_events: list[dict] = []
+    response_output = run_ai_with_tools(ctx, profile, user_input, memory_context, tool_events)
+    trace = AITrace(
+        ai_name=expr.ai_name,
+        ai_profile_name=expr.ai_name,
+        agent_name=None,
+        model=profile.model,
+        system_prompt=profile.system_prompt,
+        input=user_input,
+        output=response_output,
+        memory=memory_context,
+        tool_calls=[e for e in tool_events if e.get("type") == "call"],
+        tool_results=[e for e in tool_events if e.get("type") == "result"],
+    )
+    ctx.traces.append(trace)
+    if expr.target in ctx.constants:
+        raise Namel3ssError(f"Cannot assign to constant '{expr.target}'", line=expr.line, column=expr.column)
+    ctx.locals[expr.target] = response_output
+    ctx.last_value = response_output
+    ctx.memory_manager.record_interaction(profile, ctx.state, user_input, response_output, tool_events)
+    return response_output
+
+
+def run_ai_with_tools(
+    ctx: ExecutionContext,
+    profile: ir.AIDecl,
+    user_input: str,
+    memory_context: dict,
+    tool_events: list[dict],
+) -> str:
+    max_calls = 3
+    tool_results: list[dict] = []
+    provider_name = getattr(profile, "provider", "mock") or "mock"
+    for _ in range(max_calls + 1):
+        provider = _resolve_provider(ctx, provider_name)
+        response = provider.ask(
+            model=profile.model,
+            system_prompt=profile.system_prompt,
+            user_input=user_input,
+            tools=[{"name": name} for name in profile.exposed_tools],
+            memory=memory_context,
+            tool_results=tool_results,
+        )
+        if isinstance(response, AIToolCallResponse):
+            if response.tool_name not in profile.exposed_tools:
+                raise Namel3ssError(f"AI requested unexposed tool '{response.tool_name}'")
+            if not isinstance(response.args, dict):
+                raise Namel3ssError("Tool call args must be a dictionary")
+            tool_events.append({"type": "call", "name": response.tool_name, "args": response.args})
+            result = execute_tool(response.tool_name, response.args)
+            tool_events.append({"type": "result", "name": response.tool_name, "result": result})
+            tool_results.append({"name": response.tool_name, "result": result})
+            continue
+        if not isinstance(response.output, str):
+            raise Namel3ssError("AI response must be a string")
+        return response.output
+    raise Namel3ssError("AI exceeded maximum tool calls")
+
+
+def _resolve_provider(ctx: ExecutionContext, provider_name: str):
+    key = provider_name.lower()
+    if key in ctx.provider_cache:
+        return ctx.provider_cache[key]
+    provider = get_provider(key, ctx.config)
+    ctx.provider_cache[key] = provider
+    return provider

namel3ss/runtime/executor/api.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.ai.provider import AIProvider
+from namel3ss.runtime.executor.executor import Executor
+from namel3ss.runtime.executor.result import ExecutionResult
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.schema.records import RecordSchema
+
+
+def execute_flow(
+    flow: ir.Flow,
+    schemas: Optional[Dict[str, RecordSchema]] = None,
+    initial_state: Optional[Dict[str, object]] = None,
+    input_data: Optional[Dict[str, object]] = None,
+    ai_provider: Optional[AIProvider] = None,
+    ai_profiles: Optional[Dict[str, ir.AIDecl]] = None,
+) -> ExecutionResult:
+    return Executor(
+        flow,
+        schemas=schemas,
+        initial_state=initial_state,
+        input_data=input_data,
+        ai_provider=ai_provider,
+        ai_profiles=ai_profiles,
+    ).run()
+
+
+def execute_program_flow(
+    program: ir.Program,
+    flow_name: str,
+    *,
+    state: Optional[Dict[str, object]] = None,
+    input: Optional[Dict[str, object]] = None,
+    store: Optional[MemoryStore] = None,
+    ai_provider: Optional[AIProvider] = None,
+) -> ExecutionResult:
+    flow = next((f for f in program.flows if f.name == flow_name), None)
+    if flow is None:
+        raise Namel3ssError(f"Unknown flow '{flow_name}'")
+    schemas = {schema.name: schema for schema in program.records}
+    return Executor(
+        flow,
+        schemas=schemas,
+        initial_state=state,
+        input_data=input,
+        store=store,
+        ai_provider=ai_provider,
+        ai_profiles=program.ais,
+        agents=program.agents,
+    ).run()

namel3ss/runtime/executor/assign.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Dict
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.executor.context import ExecutionContext
+
+
+def assign(ctx: ExecutionContext, target: ir.Assignable, value: object, origin: ir.Statement) -> None:
+    if isinstance(target, ir.VarReference):
+        if target.name not in ctx.locals:
+            raise Namel3ssError(
+                f"Cannot set undeclared variable '{target.name}'",
+                line=origin.line,
+                column=origin.column,
+            )
+        if target.name in ctx.constants:
+            raise Namel3ssError(
+                f"Cannot set constant '{target.name}'",
+                line=origin.line,
+                column=origin.column,
+            )
+        ctx.locals[target.name] = value
+        return
+
+    if isinstance(target, ir.StatePath):
+        assign_state_path(ctx.state, target, value)
+        return
+
+    raise Namel3ssError(f"Unsupported assignment target: {type(target)}", line=origin.line, column=origin.column)
+
+
+def assign_state_path(state: Dict[str, object], target: ir.StatePath, value: object) -> None:
+    cursor: Dict[str, object] = state
+    for segment in target.path[:-1]:
+        if segment not in cursor or not isinstance(cursor[segment], dict):
+            cursor[segment] = {}
+        cursor = cursor[segment]  # type: ignore[assignment]
+    cursor[target.path[-1]] = value

namel3ss/runtime/executor/context.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from namel3ss.config.model import AppConfig
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.ai.provider import AIProvider
+from namel3ss.runtime.ai.trace import AITrace
+from namel3ss.runtime.memory.manager import MemoryManager
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.schema.records import RecordSchema
+
+
+@dataclass
+class ExecutionContext:
+    flow: ir.Flow
+    schemas: Dict[str, RecordSchema]
+    state: Dict[str, object]
+    locals: Dict[str, object]
+    constants: set[str]
+    last_value: Optional[object]
+    store: MemoryStore
+    ai_provider: AIProvider
+    ai_profiles: Dict[str, ir.AIDecl]
+    agents: Dict[str, ir.AgentDecl]
+    traces: list[AITrace]
+    memory_manager: MemoryManager
+    agent_calls: int
+    config: AppConfig
+    provider_cache: Dict[str, AIProvider]