namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/__init__.py

@@ -0,0 +1,4 @@
+"""
+Namel3ss: an English-first, AI-native full-stack programming language runtime package.
+"""
+

namel3ss/ast/__init__.py

@@ -0,0 +1,5 @@
+"""Abstract syntax tree definitions for Namel3ss."""
+
+from namel3ss.ast import nodes  # noqa: F401
+
+__all__ = ["nodes"]

namel3ss/ast/agents.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from namel3ss.ast.base import Node
+
+
+@dataclass
+class AgentDecl(Node):
+    name: str
+    ai_name: str
+    system_prompt: Optional[str]

namel3ss/ast/ai.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from namel3ss.ast.base import Node
+
+
+@dataclass
+class AIMemory(Node):
+    short_term: int = 0
+    semantic: bool = False
+    profile: bool = False
+
+
+@dataclass
+class AIDecl(Node):
+    name: str
+    model: str
+    provider: str | None
+    system_prompt: Optional[str]
+    exposed_tools: List[str]
+    memory: AIMemory

namel3ss/ast/base.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Node:
+    line: Optional[int]
+    column: Optional[int]

namel3ss/ast/expressions.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+from namel3ss.ast.base import Node
+
+
+@dataclass
+class Expression(Node):
+    pass
+
+
+@dataclass
+class Literal(Expression):
+    value: Union[str, int, bool]
+
+
+@dataclass
+class VarReference(Expression):
+    name: str
+
+
+@dataclass
+class AttrAccess(Expression):
+    base: str
+    attrs: List[str]
+
+
+@dataclass
+class StatePath(Expression):
+    path: List[str]
+
+
+@dataclass
+class UnaryOp(Expression):
+    op: str
+    operand: Expression
+
+
+@dataclass
+class BinaryOp(Expression):
+    op: str
+    left: Expression
+    right: Expression
+
+
+@dataclass
+class Comparison(Expression):
+    kind: str  # eq, gt, lt
+    left: Expression
+    right: Expression
+
+
+Assignable = Union[VarReference, StatePath]

namel3ss/ast/nodes.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+from namel3ss.ast.agents import AgentDecl
+from namel3ss.ast.ai import AIDecl, AIMemory
+from namel3ss.ast.base import Node
+from namel3ss.ast.expressions import (
+    Assignable,
+    AttrAccess,
+    BinaryOp,
+    Comparison,
+    Expression,
+    Literal,
+    StatePath,
+    UnaryOp,
+    VarReference,
+)
+from namel3ss.ast.pages import ButtonItem, FormItem, PageDecl, PageItem, TableItem, TextItem, TitleItem
+from namel3ss.ast.program import Flow, Program
+from namel3ss.ast.statements import (
+    AskAIStmt,
+    Find,
+    ForEach,
+    If,
+    Let,
+    Match,
+    MatchCase,
+    ParallelAgentEntry,
+    Repeat,
+    Return,
+    RunAgentStmt,
+    RunAgentsParallelStmt,
+    Save,
+    Set,
+    Statement,
+    TryCatch,
+)
+from namel3ss.ast.tool import ToolDecl
+from namel3ss.ast.records import FieldConstraint, FieldDecl, RecordDecl
+
+__all__ = [
+    "Node",
+    "Flow",
+    "Program",
+    "Statement",
+    "Let",
+    "Set",
+    "If",
+    "Return",
+    "AskAIStmt",
+    "RunAgentStmt",
+    "ParallelAgentEntry",
+    "RunAgentsParallelStmt",
+    "Repeat",
+    "ForEach",
+    "MatchCase",
+    "Match",
+    "TryCatch",
+    "Save",
+    "Find",
+    "Expression",
+    "Literal",
+    "VarReference",
+    "AttrAccess",
+    "StatePath",
+    "UnaryOp",
+    "BinaryOp",
+    "Comparison",
+    "Assignable",
+    "FieldConstraint",
+    "FieldDecl",
+    "RecordDecl",
+    "PageItem",
+    "TitleItem",
+    "TextItem",
+    "FormItem",
+    "TableItem",
+    "ButtonItem",
+    "PageDecl",
+    "AIDecl",
+    "AIMemory",
+    "ToolDecl",
+    "AgentDecl",
+]

namel3ss/ast/pages.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from namel3ss.ast.base import Node
+
+
+@dataclass
+class PageItem(Node):
+    pass
+
+
+@dataclass
+class TitleItem(PageItem):
+    value: str
+
+
+@dataclass
+class TextItem(PageItem):
+    value: str
+
+
+@dataclass
+class FormItem(PageItem):
+    record_name: str
+
+
+@dataclass
+class TableItem(PageItem):
+    record_name: str
+
+
+@dataclass
+class ButtonItem(PageItem):
+    label: str
+    flow_name: str
+
+
+@dataclass
+class PageDecl(Node):
+    name: str
+    items: List[PageItem]

namel3ss/ast/program.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from namel3ss.ast.base import Node
+
+
+@dataclass
+class Flow(Node):
+    name: str
+    body: List["Statement"]
+
+
+@dataclass
+class Program(Node):
+    records: List["RecordDecl"]
+    flows: List[Flow]
+    pages: List["PageDecl"]
+    ais: List["AIDecl"]
+    tools: List["ToolDecl"]
+    agents: List["AgentDecl"]

namel3ss/ast/records.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from namel3ss.ast.base import Node
+from namel3ss.ast.expressions import Expression
+
+
+@dataclass
+class FieldConstraint(Node):
+    kind: str  # present, unique, gt, lt, pattern, len_min, len_max
+    expression: Optional[Expression] = None
+    pattern: Optional[str] = None
+
+
+@dataclass
+class FieldDecl(Node):
+    name: str
+    type_name: str
+    constraint: Optional[FieldConstraint]
+
+
+@dataclass
+class RecordDecl(Node):
+    name: str
+    fields: List[FieldDecl]

namel3ss/ast/statements.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from namel3ss.ast.base import Node
+from namel3ss.ast.expressions import Assignable, Expression
+
+
+@dataclass
+class Statement(Node):
+    pass
+
+
+@dataclass
+class Let(Statement):
+    name: str
+    expression: Expression
+    constant: bool = False
+
+
+@dataclass
+class Set(Statement):
+    target: Assignable
+    expression: Expression
+
+
+@dataclass
+class If(Statement):
+    condition: Expression
+    then_body: List[Statement]
+    else_body: List[Statement]
+
+
+@dataclass
+class Return(Statement):
+    expression: Expression
+
+
+@dataclass
+class AskAIStmt(Statement):
+    ai_name: str
+    input_expr: Expression
+    target: str
+
+
+@dataclass
+class RunAgentStmt(Statement):
+    agent_name: str
+    input_expr: Expression
+    target: str
+
+
+@dataclass
+class ParallelAgentEntry(Node):
+    agent_name: str
+    input_expr: Expression
+
+
+@dataclass
+class RunAgentsParallelStmt(Statement):
+    entries: List[ParallelAgentEntry]
+    target: str
+
+
+@dataclass
+class Repeat(Statement):
+    count: Expression
+    body: List[Statement]
+
+
+@dataclass
+class ForEach(Statement):
+    name: str
+    iterable: Expression
+    body: List[Statement]
+
+
+@dataclass
+class MatchCase(Node):
+    pattern: Expression
+    body: List[Statement]
+
+
+@dataclass
+class Match(Statement):
+    expression: Expression
+    cases: List[MatchCase]
+    otherwise: Optional[List[Statement]]
+
+
+@dataclass
+class TryCatch(Statement):
+    try_body: List[Statement]
+    catch_var: str
+    catch_body: List[Statement]
+
+
+@dataclass
+class Save(Statement):
+    record_name: str
+
+
+@dataclass
+class Find(Statement):
+    record_name: str
+    predicate: Expression

namel3ss/ast/tool.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from namel3ss.ast.base import Node
+
+
+@dataclass
+class ToolDecl(Node):
+    name: str
+    kind: str

namel3ss/cli/__init__.py

@@ -0,0 +1,2 @@
+"""Command-line interface for Namel3ss."""
+

namel3ss/cli/actions_mode.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.ui.manifest import build_manifest
+
+
+def list_actions(program_ir, json_mode: bool) -> tuple[dict | None, str | None]:
+    manifest = build_manifest(program_ir, state={}, store=MemoryStore())
+    actions = manifest.get("actions", {})
+    sorted_ids = sorted(actions.keys())
+    if json_mode:
+        data = []
+        for action_id in sorted_ids:
+            entry = actions[action_id]
+            item = {"id": action_id, "type": entry.get("type")}
+            if entry.get("type") == "call_flow":
+                item["flow"] = entry.get("flow")
+            if entry.get("type") == "submit_form":
+                item["record"] = entry.get("record")
+            data.append(item)
+        return (
+            {
+                "ok": True,
+                "count": len(data),
+                "actions": data,
+            },
+            None,
+        )
+    lines = []
+    for action_id in sorted_ids:
+        entry = actions[action_id]
+        details: list[str] = []
+        if entry.get("type") == "call_flow" and entry.get("flow"):
+            details.append(f"flow={entry['flow']}")
+        if entry.get("type") == "submit_form" and entry.get("record"):
+            details.append(f"record={entry['record']}")
+        detail_str = f"  {' '.join(details)}" if details else ""
+        lines.append(f"{action_id}  {entry.get('type')} {detail_str}".rstrip())
+    return None, "\n".join(lines)

namel3ss/cli/app_loader.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir.nodes import lower_program
+from namel3ss.parser.core import parse
+from namel3ss.config.dotenv import apply_dotenv, load_dotenv_for_path
+
+
+def load_program(path_str: str) -> tuple[object, str]:
+    path = Path(path_str)
+    if path.suffix != ".ai":
+        raise Namel3ssError("Input file must have .ai extension")
+    apply_dotenv(load_dotenv_for_path(str(path)))
+    try:
+        source = path.read_text(encoding="utf-8")
+    except FileNotFoundError as err:
+        raise Namel3ssError(f"File not found: {path}") from err
+    ast_program = parse(source)
+    program_ir = lower_program(ast_program)
+    return program_ir, source

namel3ss/cli/commands/action.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import sys
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.ir.nodes import lower_program
+from namel3ss.parser.core import parse
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.runtime.ui.actions import handle_action
+from namel3ss.cli.io.json_io import dumps_pretty, parse_json
+from namel3ss.cli.io.read_source import read_source
+
+
+def run(args) -> int:
+    source = ""
+    try:
+        source, _ = read_source(args.path)
+        ast_program = parse(source)
+        program_ir = lower_program(ast_program)
+        payload = parse_json(args.payload or "{}")
+        response = handle_action(program_ir, action_id=args.id, payload=payload, state={}, store=MemoryStore())
+        print(dumps_pretty(response))
+        return 0
+    except Namel3ssError as err:
+        print(format_error(err, source), file=sys.stderr)
+        return 1

namel3ss/cli/commands/run.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import sys
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.ir.nodes import lower_program
+from namel3ss.parser.core import parse
+from namel3ss.runtime.executor import execute_program_flow
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.cli.io.json_io import dumps_pretty
+from namel3ss.cli.io.read_source import read_source
+
+
+def run(args) -> int:
+    source = ""
+    try:
+        source, path = read_source(args.path)
+        ast_program = parse(source)
+        program_ir = lower_program(ast_program)
+        flow_name = _select_flow(program_ir, args.flow)
+        result = execute_program_flow(program_ir, flow_name, state={}, input={}, store=MemoryStore())
+        traces = [_trace_to_dict(t) for t in result.traces]
+        output = {"ok": True, "state": result.state, "result": result.last_value, "traces": traces}
+        print(dumps_pretty(output))
+        return 0
+    except Namel3ssError as err:
+        print(format_error(err, source), file=sys.stderr)
+        return 1
+
+
+def _select_flow(program_ir, flow_flag: str | None) -> str:
+    if flow_flag:
+        return flow_flag
+    if len(program_ir.flows) == 1:
+        return program_ir.flows[0].name
+    raise Namel3ssError("Multiple flows found; specify --flow")
+
+
+def _trace_to_dict(trace) -> dict:
+    if hasattr(trace, "__dict__"):
+        return trace.__dict__
+    return trace if isinstance(trace, dict) else {"value": trace}

namel3ss/cli/commands/ui.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import sys
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.ir.nodes import lower_program
+from namel3ss.parser.core import parse
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.ui.manifest import build_manifest
+from namel3ss.cli.io.json_io import dumps_pretty
+from namel3ss.cli.io.read_source import read_source
+
+
+def run(args) -> int:
+    source = ""
+    try:
+        source, _ = read_source(args.path)
+        ast_program = parse(source)
+        program_ir = lower_program(ast_program)
+        manifest = build_manifest(program_ir, state={}, store=MemoryStore())
+        print(dumps_pretty(manifest))
+        return 0
+    except Namel3ssError as err:
+        print(format_error(err, source), file=sys.stderr)
+        return 1

namel3ss/cli/commands/validate.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import sys
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.ir.nodes import lower_program
+from namel3ss.parser.core import parse
+
+
+def run(args) -> int:
+    source = ""
+    try:
+        from namel3ss.cli.io.read_source import read_source
+
+        source, _ = read_source(args.path)
+        ast_program = parse(source)
+        lower_program(ast_program)
+        print("Validation succeeded.")
+        return 0
+    except Namel3ssError as err:
+        print(format_error(err, source), file=sys.stderr)
+        return 1

namel3ss/cli/format_mode.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.format.formatter import format_source
+
+
+def run_format(path_str: str, check_only: bool) -> int:
+    path = Path(path_str)
+    if path.suffix != ".ai":
+        raise Namel3ssError("Input file must have .ai extension")
+    try:
+        source = path.read_text(encoding="utf-8")
+    except FileNotFoundError as err:
+        raise Namel3ssError(f"File not found: {path}") from err
+    formatted = format_source(source)
+    if check_only:
+        if formatted == source:
+            print("OK")
+            return 0
+        print("Needs formatting")
+        return 1
+    if formatted == source:
+        print("Already formatted")
+        return 0
+    path.write_text(formatted, encoding="utf-8")
+    print("Formatted")
+    return 0

namel3ss/cli/io/json_io.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import json
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def parse_json(text: str) -> dict:
+    try:
+        data = json.loads(text) if text else {}
+    except json.JSONDecodeError as exc:
+        raise Namel3ssError(f"Invalid JSON payload: {exc.msg}") from exc
+    if not isinstance(data, dict):
+        raise Namel3ssError("Payload JSON must be an object")
+    return data
+
+
+def dumps_pretty(obj: object) -> str:
+    return json.dumps(obj, indent=2, ensure_ascii=False)

namel3ss/cli/io/read_source.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def read_source(path_str: str) -> tuple[str, str]:
+    path = Path(path_str)
+    if path.suffix != ".ai":
+        raise Namel3ssError("Input file must have .ai extension")
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError as err:
+        raise Namel3ssError(f"File not found: {path}") from err
+    return text, str(path)