namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/parser/flow.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import List, Set
+
+from namel3ss.ast import nodes as ast
+
+
+def parse_flow(parser) -> ast.Flow:
+    flow_tok = parser._expect("FLOW", "Expected 'flow' declaration")
+    name_tok = parser._expect("STRING", "Expected flow name string")
+    parser._expect("COLON", "Expected ':' after flow name")
+    parser._expect("NEWLINE", "Expected newline after flow header")
+    parser._expect("INDENT", "Expected indented block for flow body")
+    body = parse_statements(parser, until={"DEDENT"})
+    parser._expect("DEDENT", "Expected block end")
+    while parser._match("NEWLINE"):
+        pass
+    return ast.Flow(name=name_tok.value, body=body, line=flow_tok.line, column=flow_tok.column)
+
+
+def parse_statements(parser, until: Set[str]) -> List[ast.Statement]:
+    statements: List[ast.Statement] = []
+    while parser._current().type not in until:
+        if parser._match("NEWLINE"):
+            continue
+        statements.append(parser._parse_statement())
+    return statements
+
+
+def parse_block(parser) -> List[ast.Statement]:
+    parser._expect("NEWLINE", "Expected newline before block")
+    parser._expect("INDENT", "Expected indented block")
+    stmts = parse_statements(parser, until={"DEDENT"})
+    parser._expect("DEDENT", "Expected end of block")
+    while parser._match("NEWLINE"):
+        pass
+    return stmts

namel3ss/parser/pages.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import List
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_page(parser) -> ast.PageDecl:
+    page_tok = parser._advance()
+    name_tok = parser._expect("STRING", "Expected page name string")
+    parser._expect("COLON", "Expected ':' after page name")
+    parser._expect("NEWLINE", "Expected newline after page header")
+    parser._expect("INDENT", "Expected indented page body")
+    items: List[ast.PageItem] = []
+    while parser._current().type != "DEDENT":
+        if parser._match("NEWLINE"):
+            continue
+        items.append(parse_page_item(parser))
+    parser._expect("DEDENT", "Expected end of page body")
+    return ast.PageDecl(name=name_tok.value, items=items, line=page_tok.line, column=page_tok.column)
+
+
+def parse_page_item(parser) -> ast.PageItem:
+    tok = parser._current()
+    if tok.type == "TITLE":
+        parser._advance()
+        parser._expect("IS", "Expected 'is' after 'title'")
+        value_tok = parser._expect("STRING", "Expected title string")
+        return ast.TitleItem(value=value_tok.value, line=tok.line, column=tok.column)
+    if tok.type == "TEXT":
+        parser._advance()
+        parser._expect("IS", "Expected 'is' after 'text'")
+        value_tok = parser._expect("STRING", "Expected text string")
+        return ast.TextItem(value=value_tok.value, line=tok.line, column=tok.column)
+    if tok.type == "FORM":
+        parser._advance()
+        parser._expect("IS", "Expected 'is' after 'form'")
+        value_tok = parser._expect("STRING", "Expected form record name")
+        return ast.FormItem(record_name=value_tok.value, line=tok.line, column=tok.column)
+    if tok.type == "TABLE":
+        parser._advance()
+        parser._expect("IS", "Expected 'is' after 'table'")
+        value_tok = parser._expect("STRING", "Expected table record name")
+        return ast.TableItem(record_name=value_tok.value, line=tok.line, column=tok.column)
+    if tok.type == "BUTTON":
+        parser._advance()
+        label_tok = parser._expect("STRING", "Expected button label string")
+        if parser._match("CALLS"):
+            raise Namel3ssError(
+                'Buttons must use a block. Use: button "Run": NEWLINE indent calls flow "demo"',
+                line=tok.line,
+                column=tok.column,
+            )
+        parser._expect("COLON", "Expected ':' after button label")
+        parser._expect("NEWLINE", "Expected newline after button header")
+        parser._expect("INDENT", "Expected indented button body")
+        flow_tok = None
+        while parser._current().type != "DEDENT":
+            if parser._match("NEWLINE"):
+                continue
+            parser._expect("CALLS", "Expected 'calls' in button action")
+            parser._expect("FLOW", "Expected 'flow' keyword in button action")
+            flow_tok = parser._expect("STRING", "Expected flow name string")
+            if parser._match("NEWLINE"):
+                continue
+            break
+        parser._expect("DEDENT", "Expected end of button body")
+        if flow_tok is None:
+            raise Namel3ssError("Button body must include 'calls flow \"<name>\"'", line=tok.line, column=tok.column)
+        return ast.ButtonItem(label=label_tok.value, flow_name=flow_tok.value, line=tok.line, column=tok.column)
+    raise Namel3ssError(
+        f"Pages are declarative; unexpected item '{tok.type.lower()}'",
+        line=tok.line,
+        column=tok.column,
+    )

namel3ss/parser/program.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import List
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.parser.agent import parse_agent_decl
+from namel3ss.parser.ai import parse_ai_decl
+from namel3ss.parser.flow import parse_flow
+from namel3ss.parser.pages import parse_page
+from namel3ss.parser.records import parse_record
+from namel3ss.parser.tool import parse_tool
+
+
+def parse_program(parser) -> ast.Program:
+    records: List[ast.RecordDecl] = []
+    flows: List[ast.Flow] = []
+    pages: List[ast.PageDecl] = []
+    ais: List[ast.AIDecl] = []
+    tools: List[ast.ToolDecl] = []
+    agents: List[ast.AgentDecl] = []
+    while parser._current().type != "EOF":
+        if parser._match("NEWLINE"):
+            continue
+        if parser._current().type == "TOOL":
+            tools.append(parse_tool(parser))
+            continue
+        if parser._current().type == "AGENT":
+            agents.append(parse_agent_decl(parser))
+            continue
+        if parser._current().type == "AI":
+            ais.append(parse_ai_decl(parser))
+            continue
+        if parser._current().type == "RECORD":
+            records.append(parse_record(parser))
+            continue
+        if parser._current().type == "FLOW":
+            flows.append(parse_flow(parser))
+            continue
+        if parser._current().type == "PAGE":
+            pages.append(parse_page(parser))
+            continue
+        tok = parser._current()
+        raise Namel3ssError("Unexpected top-level token", line=tok.line, column=tok.column)
+    return ast.Program(records=records, flows=flows, pages=pages, ais=ais, tools=tools, agents=agents, line=None, column=None)

namel3ss/parser/records.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import List
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.lexer.tokens import Token
+from namel3ss.parser.constraints import parse_field_constraint
+
+
+def parse_record(parser) -> ast.RecordDecl:
+    rec_tok = parser._advance()
+    name_tok = parser._expect("STRING", "Expected record name string")
+    parser._expect("COLON", "Expected ':' after record name")
+    fields = parse_record_fields(parser)
+    return ast.RecordDecl(name=name_tok.value, fields=fields, line=rec_tok.line, column=rec_tok.column)
+
+
+def parse_record_fields(parser) -> List[ast.FieldDecl]:
+    parser._expect("NEWLINE", "Expected newline after record header")
+    parser._expect("INDENT", "Expected indented record body")
+    fields: List[ast.FieldDecl] = []
+    while parser._current().type != "DEDENT":
+        if parser._match("NEWLINE"):
+            continue
+        name_tok = parser._current()
+        if name_tok.type not in {"IDENT", "TITLE", "TEXT", "FORM", "TABLE", "BUTTON", "PAGE"}:
+            raise Namel3ssError("Expected field name", line=name_tok.line, column=name_tok.column)
+        parser._advance()
+        type_tok = parser._current()
+        if not type_tok.type.startswith("TYPE_"):
+            raise Namel3ssError("Expected field type", line=type_tok.line, column=type_tok.column)
+        parser._advance()
+        type_name = type_from_token(type_tok)
+        constraint = None
+        if parser._match("MUST"):
+            constraint = parse_field_constraint(parser)
+        fields.append(
+            ast.FieldDecl(
+                name=name_tok.value,
+                type_name=type_name,
+                constraint=constraint,
+                line=name_tok.line,
+                column=name_tok.column,
+            )
+        )
+        if parser._match("NEWLINE"):
+            continue
+    parser._expect("DEDENT", "Expected end of record body")
+    while parser._match("NEWLINE"):
+        pass
+    return fields
+
+
+def type_from_token(tok: Token) -> str:
+    if tok.type == "TYPE_STRING":
+        return "string"
+    if tok.type == "TYPE_INT":
+        return "int"
+    if tok.type == "TYPE_NUMBER":
+        return "number"
+    if tok.type == "TYPE_BOOLEAN":
+        return "boolean"
+    if tok.type == "TYPE_JSON":
+        return "json"
+    raise Namel3ssError("Invalid type", line=tok.line, column=tok.column)

namel3ss/parser/statements/__init__.py

@@ -0,0 +1,27 @@
+from namel3ss.parser.statements.core import parse_statement, parse_target, validate_match_pattern
+from namel3ss.parser.statements.control_flow import (
+    parse_for_each,
+    parse_if,
+    parse_match,
+    parse_repeat,
+    parse_return,
+    parse_try,
+)
+from namel3ss.parser.statements.data import parse_find, parse_save
+from namel3ss.parser.statements.letset import parse_let, parse_set
+
+__all__ = [
+    "parse_statement",
+    "parse_let",
+    "parse_set",
+    "parse_if",
+    "parse_return",
+    "parse_repeat",
+    "parse_for_each",
+    "parse_match",
+    "parse_try",
+    "parse_save",
+    "parse_find",
+    "parse_target",
+    "validate_match_pattern",
+]

namel3ss/parser/statements/control_flow.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import List
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_if(parser) -> ast.If:
+    if_tok = parser._advance()
+    condition = parser._parse_expression()
+    parser._expect("COLON", "Expected ':' after condition")
+    parser._expect("NEWLINE", "Expected newline after condition")
+    parser._expect("INDENT", "Expected indented block for if body")
+    then_body = parser._parse_statements(until={"DEDENT"})
+    parser._expect("DEDENT", "Expected block end")
+    else_body: List[ast.Statement] = []
+    while parser._match("NEWLINE"):
+        pass
+    if parser._match("ELSE"):
+        parser._expect("COLON", "Expected ':' after else")
+        parser._expect("NEWLINE", "Expected newline after else")
+        parser._expect("INDENT", "Expected indented block for else body")
+        else_body = parser._parse_statements(until={"DEDENT"})
+        parser._expect("DEDENT", "Expected block end")
+        while parser._match("NEWLINE"):
+            pass
+    return ast.If(
+        condition=condition,
+        then_body=then_body,
+        else_body=else_body,
+        line=if_tok.line,
+        column=if_tok.column,
+    )
+
+
+def parse_return(parser) -> ast.Return:
+    ret_tok = parser._advance()
+    expr = parser._parse_expression()
+    return ast.Return(expression=expr, line=ret_tok.line, column=ret_tok.column)
+
+
+def parse_repeat(parser) -> ast.Repeat:
+    rep_tok = parser._advance()
+    parser._expect("UP", "Expected 'up' in repeat statement")
+    parser._expect("TO", "Expected 'to' in repeat statement")
+    count_expr = parser._parse_expression()
+    parser._expect("TIMES", "Expected 'times' after repeat count")
+    parser._expect("COLON", "Expected ':' after repeat header")
+    body = parser._parse_block()
+    return ast.Repeat(count=count_expr, body=body, line=rep_tok.line, column=rep_tok.column)
+
+
+def parse_for_each(parser) -> ast.ForEach:
+    for_tok = parser._advance()
+    parser._expect("EACH", "Expected 'each' after 'for'")
+    name_tok = parser._expect("IDENT", "Expected loop variable name")
+    parser._expect("IN", "Expected 'in' in for-each loop")
+    iterable = parser._parse_expression()
+    parser._expect("COLON", "Expected ':' after for-each header")
+    body = parser._parse_block()
+    return ast.ForEach(name=name_tok.value, iterable=iterable, body=body, line=for_tok.line, column=for_tok.column)
+
+
+def parse_match(parser) -> ast.Match:
+    match_tok = parser._advance()
+    expr = parser._parse_expression()
+    parser._expect("COLON", "Expected ':' after match expression")
+    parser._expect("NEWLINE", "Expected newline after match header")
+    parser._expect("INDENT", "Expected indented match body")
+    parser._expect("WITH", "Expected 'with' inside match")
+    parser._expect("COLON", "Expected ':' after 'with'")
+    parser._expect("NEWLINE", "Expected newline after 'with:'")
+    parser._expect("INDENT", "Expected indented match cases")
+    cases: List[ast.MatchCase] = []
+    otherwise_body: List[ast.Statement] | None = None
+    while parser._current().type not in {"DEDENT"}:
+        if parser._match("WHEN"):
+            pattern_expr = parser._parse_expression()
+            parser._validate_match_pattern(pattern_expr)
+            parser._expect("COLON", "Expected ':' after when pattern")
+            case_body = parser._parse_block()
+            if otherwise_body is not None:
+                raise Namel3ssError("Unreachable case after otherwise", line=pattern_expr.line, column=pattern_expr.column)
+            cases.append(ast.MatchCase(pattern=pattern_expr, body=case_body, line=pattern_expr.line, column=pattern_expr.column))
+            continue
+        if parser._match("OTHERWISE"):
+            if otherwise_body is not None:
+                tok = parser.tokens[parser.position - 1]
+                raise Namel3ssError("Duplicate otherwise in match", line=tok.line, column=tok.column)
+            parser._expect("COLON", "Expected ':' after otherwise")
+            otherwise_body = parser._parse_block()
+            continue
+        tok = parser._current()
+        raise Namel3ssError("Expected 'when' or 'otherwise' in match", line=tok.line, column=tok.column)
+    parser._expect("DEDENT", "Expected end of match cases")
+    parser._expect("DEDENT", "Expected end of match block")
+    while parser._match("NEWLINE"):
+        pass
+    if not cases and otherwise_body is None:
+        raise Namel3ssError("Match must have at least one case", line=match_tok.line, column=match_tok.column)
+    return ast.Match(expression=expr, cases=cases, otherwise=otherwise_body, line=match_tok.line, column=match_tok.column)
+
+
+def parse_try(parser) -> ast.TryCatch:
+    try_tok = parser._advance()
+    parser._expect("COLON", "Expected ':' after try")
+    try_body = parser._parse_block()
+    if not parser._match("WITH"):
+        tok = parser._current()
+        raise Namel3ssError("Expected 'with' introducing catch", line=tok.line, column=tok.column)
+    parser._expect("CATCH", "Expected 'catch' after 'with'")
+    var_tok = parser._expect("IDENT", "Expected catch variable name")
+    parser._expect("COLON", "Expected ':' after catch clause")
+    catch_body = parser._parse_block()
+    return ast.TryCatch(try_body=try_body, catch_var=var_tok.value, catch_body=catch_body, line=try_tok.line, column=try_tok.column)

namel3ss/parser/statements/core.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.parser.agent import parse_run_agent_stmt, parse_run_agents_parallel
+from namel3ss.parser.ai import parse_ask_stmt
+from namel3ss.parser.statements.control_flow import (
+    parse_for_each,
+    parse_if,
+    parse_match,
+    parse_repeat,
+    parse_return,
+    parse_try,
+)
+from namel3ss.parser.statements.data import parse_find, parse_save
+from namel3ss.parser.statements.letset import parse_let, parse_set
+
+
+def parse_statement(parser) -> ast.Statement:
+    tok = parser._current()
+    if tok.type == "LET":
+        return parse_let(parser)
+    if tok.type == "SET":
+        return parse_set(parser)
+    if tok.type == "IF":
+        return parse_if(parser)
+    if tok.type == "RETURN":
+        return parse_return(parser)
+    if tok.type == "ASK":
+        return parse_ask_stmt(parser)
+    if tok.type == "RUN":
+        next_type = parser.tokens[parser.position + 1].type
+        if next_type == "AGENT":
+            return parse_run_agent_stmt(parser)
+        if next_type == "AGENTS":
+            return parse_run_agents_parallel(parser)
+        raise Namel3ssError("Expected 'agent' or 'agents' after run", line=tok.line, column=tok.column)
+    if tok.type == "REPEAT":
+        return parse_repeat(parser)
+    if tok.type == "FOR":
+        return parse_for_each(parser)
+    if tok.type == "MATCH":
+        return parse_match(parser)
+    if tok.type == "TRY":
+        return parse_try(parser)
+    if tok.type == "SAVE":
+        return parse_save(parser)
+    if tok.type == "FIND":
+        return parse_find(parser)
+    raise Namel3ssError(f"Unexpected token '{tok.type}' in statement", line=tok.line, column=tok.column)
+
+
+def parse_target(parser) -> ast.Assignable:
+    tok = parser._current()
+    if tok.type == "STATE":
+        return parser._parse_state_path()
+    if tok.type == "IDENT":
+        name_tok = parser._advance()
+        return ast.VarReference(name=name_tok.value, line=name_tok.line, column=name_tok.column)
+    raise Namel3ssError("Expected assignment target", line=tok.line, column=tok.column)
+
+
+def validate_match_pattern(parser, pattern: ast.Expression) -> None:
+    if isinstance(pattern, (ast.Literal, ast.VarReference, ast.StatePath)):
+        return
+    raise Namel3ssError("Match patterns must be literal or identifier", line=pattern.line, column=pattern.column)

namel3ss/parser/statements/data.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast
+
+
+def parse_save(parser) -> ast.Save:
+    tok = parser._advance()
+    name_tok = parser._expect("IDENT", "Expected record name after 'save'")
+    return ast.Save(record_name=name_tok.value, line=tok.line, column=tok.column)
+
+
+def parse_find(parser) -> ast.Find:
+    tok = parser._advance()
+    name_tok = parser._expect("IDENT", "Expected record name after 'find'")
+    parser._expect("WHERE", "Expected 'where' in find statement")
+    predicate = parser._parse_expression()
+    return ast.Find(record_name=name_tok.value, predicate=predicate, line=tok.line, column=tok.column)

namel3ss/parser/statements/letset.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast
+
+
+def parse_let(parser) -> ast.Let:
+    let_tok = parser._advance()
+    name_tok = parser._expect("IDENT", "Expected identifier after 'let'")
+    parser._expect("IS", "Expected 'is' in declaration")
+    expr = parser._parse_expression()
+    constant = False
+    if parser._match("CONSTANT"):
+        constant = True
+    return ast.Let(name=name_tok.value, expression=expr, constant=constant, line=let_tok.line, column=let_tok.column)
+
+
+def parse_set(parser) -> ast.Set:
+    set_tok = parser._advance()
+    target = parser._parse_target()
+    parser._expect("IS", "Expected 'is' in assignment")
+    expr = parser._parse_expression()
+    return ast.Set(target=target, expression=expr, line=set_tok.line, column=set_tok.column)

namel3ss/parser/statements.py

@@ -0,0 +1 @@
+from namel3ss.parser.statements import *  # noqa: F401,F403

namel3ss/parser/tokens.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.lexer.tokens import Token
+
+
+def current(parser) -> Token:
+    return parser.tokens[parser.position]
+
+
+def advance(parser) -> Token:
+    tok = parser.tokens[parser.position]
+    parser.position += 1
+    return tok
+
+
+def match(parser, *types: str) -> bool:
+    if current(parser).type in types:
+        advance(parser)
+        return True
+    return False
+
+
+def expect(parser, token_type: str, message: Optional[str] = None) -> Token:
+    tok = current(parser)
+    if tok.type != token_type:
+        raise Namel3ssError(
+            message or f"Expected {token_type}, got {tok.type}",
+            line=tok.line,
+            column=tok.column,
+        )
+    advance(parser)
+    return tok

namel3ss/parser/tool.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from namel3ss.ast import nodes as ast
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_tool(parser) -> ast.ToolDecl:
+    tool_tok = parser._advance()
+    name_tok = parser._expect("STRING", "Expected tool name string")
+    parser._expect("COLON", "Expected ':' after tool name")
+    parser._expect("NEWLINE", "Expected newline after tool header")
+    parser._expect("INDENT", "Expected indented tool body")
+    kind = None
+    while parser._current().type != "DEDENT":
+        if parser._match("NEWLINE"):
+            continue
+        key_tok = parser._current()
+        if key_tok.type == "KIND":
+            parser._advance()
+            parser._expect("IS", "Expected 'is' after kind")
+            kind_tok = parser._expect("STRING", "Expected kind string")
+            kind = kind_tok.value
+        else:
+            raise Namel3ssError("Unknown field in tool declaration", line=key_tok.line, column=key_tok.column)
+        parser._match("NEWLINE")
+    parser._expect("DEDENT", "Expected end of tool body")
+    if kind is None:
+        raise Namel3ssError("Tool declaration requires a kind", line=tool_tok.line, column=tool_tok.column)
+    return ast.ToolDecl(name=name_tok.value, kind=kind, line=tool_tok.line, column=tool_tok.column)

namel3ss/runtime/__init__.py

@@ -0,0 +1,3 @@
+"""Runtime components for executing Namel3ss programs."""
+
+from namel3ss.runtime.executor import Executor, ExecutionResult, execute_flow, execute_program_flow  # noqa: F401

namel3ss/runtime/ai/http/client.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import json
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.ai.providers._shared.errors import map_http_error
+from namel3ss.runtime.ai.providers._shared.parse import json_loads_or_error
+
+
+def post_json(*, url: str, headers: dict[str, str], payload: dict, timeout_seconds: int, provider_name: str) -> dict:
+    data = json.dumps(payload).encode("utf-8")
+    request = Request(url, data=data, headers=headers)
+    try:
+        with urlopen(request, timeout=timeout_seconds) as response:
+            body = response.read()
+    except (HTTPError, URLError, TimeoutError) as err:
+        raise map_http_error(provider_name, err) from err
+    except Exception as err:  # pragma: no cover - unexpected transport errors
+        if isinstance(err, Namel3ssError):
+            raise
+        raise map_http_error(provider_name, err) from err
+    return json_loads_or_error(provider_name, body)

namel3ss/runtime/ai/mock_provider.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from namel3ss.runtime.ai.providers.mock import MockProvider
+
+__all__ = ["MockProvider"]

namel3ss/runtime/ai/provider.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class AIResponse:
+    output: str
+
+
+class AIProvider:
+    def ask(
+        self,
+        *,
+        model: str,
+        system_prompt: Optional[str],
+        user_input: str,
+        tools: Optional[List[Dict[str, object]]] = None,
+        memory: Optional[Dict[str, object]] = None,
+        tool_results: Optional[List[Dict[str, object]]] = None,
+    ) -> AIResponse:
+        raise NotImplementedError
+
+
+@dataclass
+class AIToolCallResponse:
+    tool_name: str
+    args: Dict[str, object]

namel3ss/runtime/ai/providers/__init__.py

@@ -0,0 +1,18 @@
+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
+from namel3ss.runtime.ai.providers.registry import get_provider, is_supported_provider
+
+__all__ = [
+    "MockProvider",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    "GeminiProvider",
+    "MistralProvider",
+    "get_provider",
+    "is_supported_provider",
+]

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

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from urllib.error import HTTPError, URLError
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def require_env(provider_name: str, env_var: str, value: str | None) -> str:
+    if value is None or str(value).strip() == "":
+        short_var = env_var.replace("NAMEL3SS_", "")
+        raise Namel3ssError(f"Missing {short_var} (set it in .env or export it)")
+    return value
+
+
+def map_http_error(provider_name: str, err: HTTPError | URLError | TimeoutError | Exception) -> Namel3ssError:
+    if isinstance(err, HTTPError) and err.code in {401, 403}:
+        return Namel3ssError(f"Provider '{provider_name}' authentication failed")
+    if isinstance(err, (URLError, TimeoutError)):
+        return Namel3ssError(f"Provider '{provider_name}' unreachable")
+    return Namel3ssError(f"Provider '{provider_name}' returned an invalid response")