namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/runtime/executor/executor.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from namel3ss.config.loader import load_config
+from namel3ss.config.model import AppConfig
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.ai.mock_provider import MockProvider
+from namel3ss.runtime.ai.provider import AIProvider
+from namel3ss.runtime.executor.context import ExecutionContext
+from namel3ss.runtime.executor.result import ExecutionResult
+from namel3ss.runtime.executor.signals import _ReturnSignal
+from namel3ss.runtime.executor.statements import execute_statement
+from namel3ss.runtime.memory.manager import MemoryManager
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.schema.records import RecordSchema
+
+
+class Executor:
+    def __init__(
+        self,
+        flow: ir.Flow,
+        schemas: Optional[Dict[str, RecordSchema]] = None,
+        initial_state: Optional[Dict[str, object]] = None,
+        store: Optional[MemoryStore] = None,
+        input_data: Optional[Dict[str, object]] = None,
+        ai_provider: Optional[AIProvider] = None,
+        ai_profiles: Optional[Dict[str, ir.AIDecl]] = None,
+        memory_manager: Optional[MemoryManager] = None,
+        agents: Optional[Dict[str, ir.AgentDecl]] = None,
+        config: Optional[AppConfig] = None,
+    ) -> None:
+        resolved_config = config or load_config()
+        default_ai_provider = ai_provider or MockProvider()
+        provider_cache = {"mock": default_ai_provider}
+        self.ctx = ExecutionContext(
+            flow=flow,
+            schemas=schemas or {},
+            state=initial_state or {},
+            locals={"input": input_data or {}},
+            constants=set(),
+            last_value=None,
+            store=store or MemoryStore(),
+            ai_provider=default_ai_provider,
+            ai_profiles=ai_profiles or {},
+            agents=agents or {},
+            traces=[],
+            memory_manager=memory_manager or MemoryManager(),
+            agent_calls=0,
+            config=resolved_config,
+            provider_cache=provider_cache,
+        )
+        self.flow = self.ctx.flow
+        self.schemas = self.ctx.schemas
+        self.state = self.ctx.state
+        self.locals = self.ctx.locals
+        self.constants = self.ctx.constants
+        self.last_value = self.ctx.last_value
+        self.store = self.ctx.store
+        self.ai_provider = self.ctx.ai_provider
+        self.ai_profiles = self.ctx.ai_profiles
+        self.agents = self.ctx.agents
+        self.traces = self.ctx.traces
+        self.memory_manager = self.ctx.memory_manager
+        self.agent_calls = self.ctx.agent_calls
+        self.config = self.ctx.config
+        self.provider_cache = self.ctx.provider_cache
+
+    def run(self) -> ExecutionResult:
+        try:
+            for stmt in self.ctx.flow.body:
+                execute_statement(self.ctx, stmt)
+        except _ReturnSignal as signal:
+            self.ctx.last_value = signal.value
+        self.last_value = self.ctx.last_value
+        self.agent_calls = self.ctx.agent_calls
+        return ExecutionResult(state=self.ctx.state, last_value=self.ctx.last_value, traces=self.ctx.traces)

namel3ss/runtime/executor/expr_eval.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.executor.context import ExecutionContext
+
+
+def evaluate_expression(ctx: ExecutionContext, expr: ir.Expression) -> object:
+    if isinstance(expr, ir.Literal):
+        return expr.value
+    if isinstance(expr, ir.VarReference):
+        if expr.name not in ctx.locals:
+            raise Namel3ssError(
+                f"Unknown variable '{expr.name}'",
+                line=expr.line,
+                column=expr.column,
+            )
+        return ctx.locals[expr.name]
+    if isinstance(expr, ir.AttrAccess):
+        if expr.base not in ctx.locals:
+            raise Namel3ssError(
+                f"Unknown variable '{expr.base}'",
+                line=expr.line,
+                column=expr.column,
+            )
+        value = ctx.locals[expr.base]
+        for attr in expr.attrs:
+            if isinstance(value, dict):
+                if attr not in value:
+                    raise Namel3ssError(
+                        f"Missing attribute '{attr}'",
+                        line=expr.line,
+                        column=expr.column,
+                    )
+                value = value[attr]
+                continue
+            if not hasattr(value, attr):
+                raise Namel3ssError(
+                    f"Missing attribute '{attr}'",
+                    line=expr.line,
+                    column=expr.column,
+                )
+            value = getattr(value, attr)
+        return value
+    if isinstance(expr, ir.StatePath):
+        return resolve_state_path(ctx, expr)
+    if isinstance(expr, ir.UnaryOp):
+        operand = evaluate_expression(ctx, expr.operand)
+        if expr.op == "not":
+            if not isinstance(operand, bool):
+                raise Namel3ssError("Operand to 'not' must be boolean", line=expr.line, column=expr.column)
+            return not operand
+        raise Namel3ssError(f"Unsupported unary op '{expr.op}'", line=expr.line, column=expr.column)
+    if isinstance(expr, ir.BinaryOp):
+        if expr.op == "and":
+            left = evaluate_expression(ctx, expr.left)
+            if not isinstance(left, bool):
+                raise Namel3ssError("Left operand of 'and' must be boolean", line=expr.line, column=expr.column)
+            if not left:
+                return False
+            right = evaluate_expression(ctx, expr.right)
+            if not isinstance(right, bool):
+                raise Namel3ssError("Right operand of 'and' must be boolean", line=expr.line, column=expr.column)
+            return left and right
+        if expr.op == "or":
+            left = evaluate_expression(ctx, expr.left)
+            if not isinstance(left, bool):
+                raise Namel3ssError("Left operand of 'or' must be boolean", line=expr.line, column=expr.column)
+            if left:
+                return True
+            right = evaluate_expression(ctx, expr.right)
+            if not isinstance(right, bool):
+                raise Namel3ssError("Right operand of 'or' must be boolean", line=expr.line, column=expr.column)
+            return bool(right)
+        raise Namel3ssError(f"Unsupported binary op '{expr.op}'", line=expr.line, column=expr.column)
+    if isinstance(expr, ir.Comparison):
+        left = evaluate_expression(ctx, expr.left)
+        right = evaluate_expression(ctx, expr.right)
+        if expr.kind in {"gt", "lt"}:
+            if not isinstance(left, (int, float)) or not isinstance(right, (int, float)):
+                raise Namel3ssError(
+                    "Greater/less comparisons require numbers",
+                    line=expr.line,
+                    column=expr.column,
+                )
+            return left > right if expr.kind == "gt" else left < right
+        if expr.kind == "eq":
+            return left == right
+        raise Namel3ssError(f"Unsupported comparison '{expr.kind}'", line=expr.line, column=expr.column)
+
+    raise Namel3ssError(f"Unsupported expression type: {type(expr)}", line=expr.line, column=expr.column)
+
+
+def resolve_state_path(ctx: ExecutionContext, expr: ir.StatePath) -> object:
+    cursor: object = ctx.state
+    for segment in expr.path:
+        if not isinstance(cursor, dict):
+            raise Namel3ssError(
+                f"State path '{'.'.join(expr.path)}' is not a mapping",
+                line=expr.line,
+                column=expr.column,
+            )
+        if segment not in cursor:
+            raise Namel3ssError(
+                f"Unknown state path '{'.'.join(expr.path)}'",
+                line=expr.line,
+                column=expr.column,
+            )
+        cursor = cursor[segment]
+    return cursor

namel3ss/runtime/executor/records_ops.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.executor.context import ExecutionContext
+from namel3ss.runtime.executor.expr_eval import evaluate_expression
+from namel3ss.runtime.records.service import save_record_or_raise
+from namel3ss.schema.records import RecordSchema
+
+
+def handle_save(ctx: ExecutionContext, stmt: ir.Save) -> None:
+    state_key = stmt.record_name.lower()
+    data_obj = ctx.state.get(state_key)
+    if not isinstance(data_obj, dict):
+        raise Namel3ssError(
+            f"Expected state.{state_key} to be a record dictionary",
+            line=stmt.line,
+            column=stmt.column,
+        )
+    validated = dict(data_obj)
+    saved = save_record_or_raise(
+        stmt.record_name,
+        validated,
+        ctx.schemas,
+        ctx.state,
+        ctx.store,
+        line=stmt.line,
+        column=stmt.column,
+    )
+    ctx.last_value = saved
+
+
+def handle_find(ctx: ExecutionContext, stmt: ir.Find) -> None:
+    schema = get_schema(ctx, stmt.record_name, stmt)
+
+    def predicate(record: dict) -> bool:
+        backup_locals = ctx.locals.copy()
+        try:
+            ctx.locals.update(record)
+            result = evaluate_expression(ctx, stmt.predicate)
+            if not isinstance(result, bool):
+                raise Namel3ssError(
+                    "Find predicate must evaluate to boolean",
+                    line=stmt.line,
+                    column=stmt.column,
+                )
+            return result
+        finally:
+            ctx.locals = backup_locals
+
+    results = ctx.store.find(schema, predicate)
+    result_name = f"{stmt.record_name.lower()}_results"
+    ctx.locals[result_name] = results
+    ctx.last_value = results
+
+
+def get_schema(ctx: ExecutionContext, record_name: str, stmt: ir.Statement) -> RecordSchema:
+    if record_name not in ctx.schemas:
+        raise Namel3ssError(
+            f"Unknown record '{record_name}'",
+            line=stmt.line,
+            column=stmt.column,
+        )
+    return ctx.schemas[record_name]

namel3ss/runtime/executor/result.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from namel3ss.runtime.ai.trace import AITrace
+
+
+@dataclass
+class ExecutionResult:
+    state: Dict[str, object]
+    last_value: Optional[object]
+    traces: list[AITrace]

namel3ss/runtime/executor/signals.py

@@ -0,0 +1,6 @@
+class _ReturnSignal(Exception):
+    """Internal control flow for return."""
+
+    def __init__(self, value: object) -> None:
+        super().__init__("return")
+        self.value = value

namel3ss/runtime/executor/statements.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.executor.ai_runner import execute_ask_ai
+from namel3ss.runtime.executor.agents import execute_run_agent, execute_run_agents_parallel
+from namel3ss.runtime.executor.assign import assign
+from namel3ss.runtime.executor.context import ExecutionContext
+from namel3ss.runtime.executor.expr_eval import evaluate_expression
+from namel3ss.runtime.executor.records_ops import handle_find, handle_save
+from namel3ss.runtime.executor.signals import _ReturnSignal
+
+
+def execute_statement(ctx: ExecutionContext, stmt: ir.Statement) -> None:
+    if isinstance(stmt, ir.Let):
+        value = evaluate_expression(ctx, stmt.expression)
+        ctx.locals[stmt.name] = value
+        if stmt.constant:
+            ctx.constants.add(stmt.name)
+        ctx.last_value = value
+        return
+    if isinstance(stmt, ir.Set):
+        value = evaluate_expression(ctx, stmt.expression)
+        assign(ctx, stmt.target, value, stmt)
+        ctx.last_value = value
+        return
+    if isinstance(stmt, ir.If):
+        condition_value = evaluate_expression(ctx, stmt.condition)
+        if not isinstance(condition_value, bool):
+            raise Namel3ssError(
+                "Condition must evaluate to a boolean",
+                line=stmt.line,
+                column=stmt.column,
+            )
+        branch = stmt.then_body if condition_value else stmt.else_body
+        for child in branch:
+            execute_statement(ctx, child)
+        return
+    if isinstance(stmt, ir.Return):
+        value = evaluate_expression(ctx, stmt.expression)
+        raise _ReturnSignal(value)
+    if isinstance(stmt, ir.Repeat):
+        count_value = evaluate_expression(ctx, stmt.count)
+        if not isinstance(count_value, int):
+            raise Namel3ssError("Repeat count must be an integer", line=stmt.line, column=stmt.column)
+        if count_value < 0:
+            raise Namel3ssError("Repeat count cannot be negative", line=stmt.line, column=stmt.column)
+        for _ in range(count_value):
+            for child in stmt.body:
+                execute_statement(ctx, child)
+        return
+    if isinstance(stmt, ir.ForEach):
+        iterable_value = evaluate_expression(ctx, stmt.iterable)
+        if not isinstance(iterable_value, list):
+            raise Namel3ssError("For-each expects a list", line=stmt.line, column=stmt.column)
+        for item in iterable_value:
+            ctx.locals[stmt.name] = item
+            for child in stmt.body:
+                execute_statement(ctx, child)
+        return
+    if isinstance(stmt, ir.Match):
+        subject = evaluate_expression(ctx, stmt.expression)
+        matched = False
+        for case in stmt.cases:
+            pattern_value = evaluate_expression(ctx, case.pattern)
+            if subject == pattern_value:
+                matched = True
+                for child in case.body:
+                    execute_statement(ctx, child)
+                break
+        if not matched and stmt.otherwise is not None:
+            for child in stmt.otherwise:
+                execute_statement(ctx, child)
+        return
+    if isinstance(stmt, ir.TryCatch):
+        try:
+            for child in stmt.try_body:
+                execute_statement(ctx, child)
+        except Namel3ssError as err:
+            ctx.locals[stmt.catch_var] = err
+            for child in stmt.catch_body:
+                execute_statement(ctx, child)
+        return
+    if isinstance(stmt, ir.AskAIStmt):
+        execute_ask_ai(ctx, stmt)
+        return
+    if isinstance(stmt, ir.RunAgentStmt):
+        execute_run_agent(ctx, stmt)
+        return
+    if isinstance(stmt, ir.RunAgentsParallelStmt):
+        execute_run_agents_parallel(ctx, stmt)
+        return
+    if isinstance(stmt, ir.Save):
+        handle_save(ctx, stmt)
+        return
+    if isinstance(stmt, ir.Find):
+        handle_find(ctx, stmt)
+        return
+    raise Namel3ssError(f"Unsupported statement type: {type(stmt)}", line=stmt.line, column=stmt.column)

namel3ss/runtime/memory/manager.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.memory.profile import ProfileMemory
+from namel3ss.runtime.memory.semantic import SemanticMemory
+from namel3ss.runtime.memory.short_term import ShortTermMemory
+
+
+class MemoryManager:
+    def __init__(self) -> None:
+        self.short_term = ShortTermMemory()
+        self.profile = ProfileMemory()
+        self.semantic = SemanticMemory()
+
+    def _session(self, state: Dict[str, object]) -> str:
+        if isinstance(state.get("user"), dict) and "id" in state["user"]:
+            return str(state["user"]["id"])
+        return "anonymous"
+
+    def recall_context(self, ai: ir.AIDecl, user_input: str, state: Dict[str, object]) -> dict:
+        session = self._session(state)
+        memory = ai.memory
+        context = {"short_term": [], "semantic": [], "profile": []}
+        if memory.short_term > 0:
+            context["short_term"] = self.short_term.recall(session, memory.short_term)
+        if memory.semantic:
+            context["semantic"] = self.semantic.recall(session, user_input, top_k=3)
+        if memory.profile:
+            context["profile"] = self.profile.recall(session)
+        return context
+
+    def record_interaction(
+        self,
+        ai: ir.AIDecl,
+        state: Dict[str, object],
+        user_input: str,
+        ai_output: str,
+        tool_events: List[dict],
+    ) -> None:
+        session = self._session(state)
+        message = {"role": "user", "content": user_input}
+        self.short_term.record(session, message)
+        ai_message = {"role": "ai", "content": ai_output}
+        self.short_term.record(session, ai_message)
+        if ai.memory.semantic:
+            snippet = f"user:{user_input} ai:{ai_output}"
+            if tool_events:
+                snippet += f" tools:{tool_events}"
+            self.semantic.record(session, snippet)
+

namel3ss/runtime/memory/profile.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+class ProfileMemory:
+    def __init__(self) -> None:
+        self._facts: Dict[str, Dict[str, str]] = {}
+
+    def set_fact(self, session: str, key: str, value: str) -> None:
+        facts = self._facts.setdefault(session, {})
+        facts[key] = value
+
+    def recall(self, session: str, limit: int = 20) -> List[dict]:
+        facts = self._facts.get(session, {})
+        items = list(facts.items())[:limit]
+        return [{"key": k, "value": v} for k, v in items]

namel3ss/runtime/memory/semantic.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+class SemanticMemory:
+    def __init__(self) -> None:
+        self._snippets: Dict[str, List[str]] = {}
+
+    def record(self, session: str, snippet: str) -> None:
+        self._snippets.setdefault(session, []).append(snippet)
+
+    def recall(self, session: str, query: str, top_k: int = 3) -> List[dict]:
+        snippets = self._snippets.get(session, [])
+        matches = []
+        for text in snippets:
+            score = 1 if query and query.lower() in text.lower() else 0
+            matches.append({"text": text, "score": score})
+        matches.sort(key=lambda x: x["score"], reverse=True)
+        return matches[:top_k]

namel3ss/runtime/memory/short_term.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+class ShortTermMemory:
+    def __init__(self) -> None:
+        self._messages: Dict[str, List[dict]] = {}
+
+    def record(self, session: str, message: dict) -> None:
+        messages = self._messages.setdefault(session, [])
+        messages.append(message)
+
+    def recall(self, session: str, limit: int) -> List[dict]:
+        messages = self._messages.get(session, [])
+        if limit <= 0:
+            return []
+        return messages[-limit:]

namel3ss/runtime/records/service.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.runtime.validators.constraints import collect_validation_errors, validate_record_instance
+from namel3ss.schema.records import RecordSchema
+
+
+def save_record_or_raise(
+    record_name: str,
+    values: Dict[str, object],
+    schemas: Dict[str, RecordSchema],
+    state: Dict[str, object],
+    store: MemoryStore,
+    line: int | None = None,
+    column: int | None = None,
+) -> dict:
+    saved, errors = save_record_with_errors(record_name, values, schemas, state, store)
+    if errors:
+        first = errors[0]
+        raise Namel3ssError(first["message"], line=line, column=column)
+    return saved
+
+
+def save_record_with_errors(
+    record_name: str,
+    values: Dict[str, object],
+    schemas: Dict[str, RecordSchema],
+    state: Dict[str, object],
+    store: MemoryStore,
+) -> Tuple[Optional[dict], List[Dict[str, str]]]:
+    schema = _get_schema(record_name, schemas)
+    type_errors = _type_errors(schema, values)
+    if type_errors:
+        return None, type_errors
+
+    constraint_errors = collect_validation_errors(schema, values, _literal_eval)
+    if constraint_errors:
+        return None, constraint_errors
+
+    conflict_field = store.check_unique(schema, values)
+    if conflict_field:
+        return None, [
+            {
+                "field": conflict_field,
+                "code": "unique",
+                "message": f"Field '{conflict_field}' in record '{record_name}' must be unique",
+            }
+        ]
+    try:
+        saved = store.save(schema, values)
+        return saved, []
+    except Namel3ssError as exc:
+        # Fallback for any residual unique enforcement
+        return None, [
+            {
+                "field": conflict_field or "",
+                "code": "unique",
+                "message": str(exc),
+            }
+        ]
+
+
+def _type_errors(schema: RecordSchema, data: Dict[str, object]) -> List[Dict[str, str]]:
+    errors: List[Dict[str, str]] = []
+    for field in schema.fields:
+        value = data.get(field.name)
+        if value is None:
+            continue
+        expected = field.type_name
+        if expected == "string" and not isinstance(value, str):
+            errors.append(_type_error(field.name, schema.name, "string"))
+        elif expected == "int" and not isinstance(value, int):
+            errors.append(_type_error(field.name, schema.name, "int"))
+        elif expected == "number" and not isinstance(value, (int, float)):
+            errors.append(_type_error(field.name, schema.name, "number"))
+        elif expected == "boolean" and not isinstance(value, bool):
+            errors.append(_type_error(field.name, schema.name, "boolean"))
+    return errors
+
+
+def _type_error(field: str, record: str, expected: str) -> Dict[str, str]:
+    return {
+        "field": field,
+        "code": "type",
+        "message": f"Field '{field}' in record '{record}' must be a {expected}",
+    }
+
+
+def _get_schema(name: str, schemas: Dict[str, RecordSchema]) -> RecordSchema:
+    if name not in schemas:
+        raise Namel3ssError(f"Unknown record '{name}'")
+    return schemas[name]
+
+
+def _literal_eval(expr: ir.Expression | None) -> object:
+    if expr is None:
+        return None
+    if isinstance(expr, ir.Literal):
+        return expr.value
+    raise Namel3ssError("Only literal expressions supported in schema constraints for forms")
+

namel3ss/runtime/store/__init__.py

@@ -0,0 +1,2 @@
+"""Runtime store implementations."""
+

namel3ss/runtime/store/memory_store.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Dict, List, Callable
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.schema.records import RecordSchema
+
+
+class MemoryStore:
+    def __init__(self) -> None:
+        self._data: Dict[str, List[dict]] = {}
+        self._unique_indexes: Dict[str, Dict[str, Dict[object, dict]]] = {}
+        self._counters: Dict[str, int] = {}
+
+    def save(self, schema: RecordSchema, record: dict) -> dict:
+        rec_name = schema.name
+        if rec_name not in self._data:
+            self._data[rec_name] = []
+            self._unique_indexes[rec_name] = {}
+            self._counters[rec_name] = 1
+
+        # Handle auto id
+        if "id" in schema.field_map:
+            record.setdefault("id", self._counters[rec_name])
+        else:
+            record.setdefault("_id", self._counters[rec_name])
+        self._counters[rec_name] += 1
+
+        conflict_field = self.check_unique(schema, record)
+        if conflict_field:
+            raise Namel3ssError(f"Record '{rec_name}' violates unique constraint on '{conflict_field}'")
+        for field in schema.unique_fields:
+            value = record.get(field)
+            if value is None:
+                continue
+            idx = self._unique_indexes[rec_name].setdefault(field, {})
+            idx[value] = record
+
+        self._data[rec_name].append(record)
+        return record
+
+    def find(self, schema: RecordSchema, predicate: Callable[[dict], bool]) -> List[dict]:
+        records = self._data.get(schema.name, [])
+        return [rec for rec in records if predicate(rec)]
+
+    def check_unique(self, schema: RecordSchema, record: dict) -> str | None:
+        rec_name = schema.name
+        indexes = self._unique_indexes.setdefault(rec_name, {})
+        for field in schema.unique_fields:
+            value = record.get(field)
+            if value is None:
+                continue
+            idx = indexes.setdefault(field, {})
+            if value in idx:
+                return field
+        return None
+
+    def list_records(self, schema: RecordSchema, limit: int = 20) -> List[dict]:
+        records = list(self._data.get(schema.name, []))
+        key_order = "id" if "id" in schema.field_map else "_id"
+        records.sort(key=lambda rec: rec.get(key_order, 0))
+        return records[:limit]

namel3ss/runtime/tools/registry.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Dict
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def execute_tool(name: str, args: Dict[str, object]) -> Dict[str, object]:
+    if name == "echo":
+        if not isinstance(args, dict):
+            raise Namel3ssError("Tool args must be a dictionary")
+        return {"echo": args}
+    raise Namel3ssError(f"Unknown tool '{name}'")

namel3ss/runtime/ui/__init__.py

@@ -0,0 +1,2 @@
+"""UI runtime utilities."""
+