namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/cli/json_io.py

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

namel3ss/cli/lint_mode.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.lint.engine import lint_source
+
+
+def run_lint(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
+    findings = lint_source(source)
+    output = {
+        "ok": len(findings) == 0,
+        "count": len(findings),
+        "findings": [f.to_dict() for f in findings],
+    }
+    import json
+
+    print(json.dumps(output, indent=2, ensure_ascii=False))
+    if check_only and findings:
+        return 1
+    return 0

namel3ss/cli/main.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import sys
+
+from namel3ss.cli.actions_mode import list_actions
+from namel3ss.cli.app_loader import load_program
+from namel3ss.cli.format_mode import run_format
+from namel3ss.cli.new_mode import run_new
+from namel3ss.cli.lint_mode import run_lint
+from namel3ss.cli.json_io import dumps_pretty, parse_payload
+from namel3ss.cli.runner import run_flow
+from namel3ss.cli.ui_mode import render_manifest, run_action
+from namel3ss.cli.studio_mode import run_studio
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+
+RESERVED = {"check", "ui", "flow", "help", "format", "lint", "actions", "studio"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    try:
+        if not args:
+            _print_usage()
+            return 1
+
+        if args[0] == "help":
+            _print_usage()
+            return 0
+        if args[0] == "new":
+            return run_new(args[1:])
+
+        path = args[0]
+        remainder = args[1:]
+
+        if remainder and remainder[0] == "format":
+            check_only = len(remainder) > 1 and remainder[1] == "check"
+            return run_format(path, check_only)
+        if remainder and remainder[0] == "lint":
+            check_only = len(remainder) > 1 and remainder[1] == "check"
+            return run_lint(path, check_only)
+        if remainder and remainder[0] == "actions":
+            json_mode = len(remainder) > 1 and remainder[1] == "json"
+            program_ir, source = load_program(path)
+            json_payload, text_output = list_actions(program_ir, json_mode)
+            if json_mode:
+                print(dumps_pretty(json_payload))
+            else:
+                print(text_output or "")
+            return 0
+        if remainder and remainder[0] == "studio":
+            port = 7333
+            dry = False
+            tail = remainder[1:]
+            i = 0
+            while i < len(tail):
+                if tail[i] == "--port" and i + 1 < len(tail):
+                    try:
+                        port = int(tail[i + 1])
+                    except ValueError:
+                        raise Namel3ssError("Port must be an integer")
+                    i += 2
+                    continue
+                if tail[i] == "--dry":
+                    dry = True
+                    i += 1
+                    continue
+                i += 1
+            return run_studio(path, port, dry)
+
+        program_ir, source = load_program(path)
+        if not remainder:
+            return _run_default(program_ir)
+        cmd = remainder[0]
+        tail = remainder[1:]
+        if cmd == "check":
+            print("OK")
+            return 0
+        if cmd == "ui":
+            manifest = render_manifest(program_ir)
+            print(dumps_pretty(manifest))
+            return 0
+        if cmd == "flow":
+            if not tail:
+                raise Namel3ssError('Missing flow name. Use: n3 <app.ai> flow "<name>"')
+            flow_name = tail[0]
+            output = run_flow(program_ir, flow_name)
+            print(dumps_pretty(output))
+            return 0
+        if cmd == "help":
+            _print_usage()
+            return 0
+        # action mode
+        if cmd in RESERVED:
+            raise Namel3ssError("Unexpected reserved command position")
+        action_id = cmd
+        payload_text = tail[0] if tail else "{}"
+        payload = parse_payload(payload_text)
+        response = run_action(program_ir, action_id, payload)
+        print(dumps_pretty(response))
+        return 0
+    except Namel3ssError as err:
+        print(format_error(err, locals().get("source", "")), file=sys.stderr)
+        return 1
+
+
+def _run_default(program_ir) -> int:
+    output = run_flow(program_ir, None)
+    print(dumps_pretty(output))
+    return 0
+
+
+def _print_usage() -> None:
+    usage = """Usage:
+  n3 new [template] [name]       # scaffold from a template (omit args to list)
+  n3 <app.ai>                      # run default flow
+  n3 <app.ai> check                # validate only
+  n3 <app.ai> ui                   # print UI manifest
+  n3 <app.ai> flow "<name>"        # run specific flow
+  n3 <app.ai> format               # format in place
+  n3 <app.ai> format check         # check formatting only
+  n3 <app.ai> lint                 # lint and print findings
+  n3 <app.ai> lint check           # lint, fail on findings
+  n3 <app.ai> studio [--port N]    # start Studio viewer (use --dry to skip server in tests)
+  n3 <app.ai> studio --dry         # dry run (prints URL)
+  n3 <app.ai> actions              # list actions (plain text)
+  n3 <app.ai> actions json         # list actions (JSON)
+  n3 <app.ai> <action_id> [json]   # execute UI action (payload optional)
+  n3 <app.ai> help                 # this help
+"""
+    print(usage.strip())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

namel3ss/cli/new_mode.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.format import format_source
+from namel3ss.lint.engine import lint_source
+
+
+@dataclass(frozen=True)
+class TemplateSpec:
+    name: str
+    directory: str
+    description: str
+    aliases: tuple[str, ...] = ()
+
+    def matches(self, candidate: str) -> bool:
+        normalized = candidate.lower().replace("_", "-")
+        if normalized == self.name:
+            return True
+        normalized_aliases = {alias.lower().replace("_", "-") for alias in self.aliases}
+        normalized_aliases.add(self.directory.lower().replace("_", "-"))
+        return normalized in normalized_aliases
+
+
+TEMPLATES: tuple[TemplateSpec, ...] = (
+    TemplateSpec(name="crud", directory="crud", description="CRUD dashboard with form and table."),
+    TemplateSpec(
+        name="ai-assistant",
+        directory="ai_assistant",
+        description="AI assistant over records with memory and tooling.",
+        aliases=("ai_assistant",),
+    ),
+    TemplateSpec(
+        name="multi-agent",
+        directory="multi_agent",
+        description="Planner, critic, and researcher agents sharing one assistant.",
+        aliases=("multi_agent",),
+    ),
+)
+
+
+def run_new(args: list[str]) -> int:
+    if not args:
+        print(render_templates_list())
+        return 0
+    if len(args) > 2:
+        raise Namel3ssError("Usage: n3 new <template> [project_name]")
+    template_name = args[0]
+    template = _resolve_template(template_name)
+    project_input = args[1] if len(args) == 2 else template.name
+    project_name = _normalize_project_name(project_input)
+
+    template_dir = _templates_root() / template.directory
+    if not template_dir.exists():
+        raise Namel3ssError(f"Template '{template.name}' is not installed (missing {template_dir}).")
+
+    target_dir = Path.cwd() / project_name
+    if target_dir.exists():
+        raise Namel3ssError(f"Directory already exists: {target_dir}")
+
+    try:
+        shutil.copytree(template_dir, target_dir)
+        _prepare_readme(target_dir, project_name)
+        formatted_source = _prepare_app_file(target_dir, project_name)
+    except Exception:
+        shutil.rmtree(target_dir, ignore_errors=True)
+        raise
+
+    findings = lint_source(formatted_source)
+    if findings:
+        print("Lint findings:")
+        for finding in findings:
+            location = f"[line {finding.line}, col {finding.column}] " if finding.line else ""
+            print(f"  - {location}{finding.code}: {finding.message}")
+
+    _print_success_message(project_name, target_dir)
+    return 0
+
+
+def render_templates_list() -> str:
+    longest = max(len(t.name) for t in TEMPLATES)
+    lines = ["Available templates:"]
+    for template in TEMPLATES:
+        padded = template.name.ljust(longest)
+        lines.append(f"  {padded} - {template.description}")
+    return "\n".join(lines)
+
+
+def _templates_root() -> Path:
+    return Path(__file__).resolve().parent.parent / "templates"
+
+
+def _resolve_template(name: str) -> TemplateSpec:
+    for template in TEMPLATES:
+        if template.matches(name):
+            return template
+    available = ", ".join(t.name for t in TEMPLATES)
+    raise Namel3ssError(f"Unknown template '{name}'. Available templates: {available}")
+
+
+def _normalize_project_name(name: str) -> str:
+    normalized = name.replace("-", "_")
+    normalized = re.sub(r"[^A-Za-z0-9_]+", "_", normalized).strip("_")
+    if not normalized:
+        raise Namel3ssError("Project name cannot be empty after normalization")
+    return normalized
+
+
+def _prepare_readme(target_dir: Path, project_name: str) -> None:
+    readme_path = target_dir / "README.md"
+    if not readme_path.exists():
+        raise Namel3ssError(f"Template is missing README.md at {readme_path}")
+    _rewrite_with_project_name(readme_path, project_name)
+
+
+def _prepare_app_file(target_dir: Path, project_name: str) -> str:
+    app_path = target_dir / "app.ai"
+    if not app_path.exists():
+        raise Namel3ssError(f"Template is missing app.ai at {app_path}")
+    raw = _rewrite_with_project_name(app_path, project_name)
+    formatted = format_source(raw)
+    app_mode = app_path.stat().st_mode
+    app_path.write_text(formatted, encoding="utf-8")
+    app_path.chmod(app_mode)
+    return formatted
+
+
+def _rewrite_with_project_name(path: Path, project_name: str) -> str:
+    original_mode = path.stat().st_mode
+    contents = path.read_text(encoding="utf-8")
+    updated = contents.replace("{{PROJECT_NAME}}", project_name)
+    path.write_text(updated, encoding="utf-8")
+    path.chmod(original_mode)
+    return updated
+
+
+def _print_success_message(project_name: str, target_dir: Path) -> None:
+    print(f"Created project at {target_dir}")
+    print("Next steps:")
+    print(f"  cd {project_name}")
+    print("  n3 app.ai studio")
+    print("  n3 app.ai actions")

namel3ss/cli/runner.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.executor import execute_program_flow
+from namel3ss.runtime.store.memory_store import MemoryStore
+
+
+def run_flow(program_ir, flow_name: str | None = None) -> dict:
+    selected = _select_flow(program_ir, flow_name)
+    result = execute_program_flow(program_ir, selected, state={}, input={}, store=MemoryStore())
+    traces = [_trace_to_dict(t) for t in result.traces]
+    return {"ok": True, "state": result.state, "result": result.last_value, "traces": traces}
+
+
+def _select_flow(program_ir, flow_name: str | None) -> str:
+    if flow_name:
+        return flow_name
+    if len(program_ir.flows) == 1:
+        return program_ir.flows[0].name
+    raise Namel3ssError('Multiple flows found; use: n3 <app.ai> flow "<name>"')
+
+
+def _trace_to_dict(trace) -> dict:
+    if hasattr(trace, "__dict__"):
+        return trace.__dict__
+    if isinstance(trace, dict):
+        return trace
+    return {"trace": trace}

namel3ss/cli/studio_mode.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import sys
+
+from namel3ss.cli.app_loader import load_program
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.studio.server import start_server
+
+
+def run_studio(path: str, port: int, dry: bool) -> int:
+    source = ""
+    try:
+        program_ir, source = load_program(path)
+        if dry:
+            print(f"Studio: http://127.0.0.1:{port}/")
+            return 0
+        start_server(path, port)
+        return 0
+    except Namel3ssError as err:
+        print(format_error(err, source), file=sys.stderr)
+        return 1

namel3ss/cli/ui_mode.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.runtime.ui.actions import handle_action
+from namel3ss.ui.manifest import build_manifest
+
+
+def render_manifest(program_ir) -> dict:
+    return build_manifest(program_ir, state={}, store=MemoryStore())
+
+
+def run_action(program_ir, action_id: str, payload: dict) -> dict:
+    return handle_action(program_ir, action_id=action_id, payload=payload, state={}, store=MemoryStore())

namel3ss/config/__init__.py

@@ -0,0 +1,4 @@
+from namel3ss.config.loader import load_config
+from namel3ss.config.model import AppConfig, OllamaConfig
+
+__all__ = ["load_config", "AppConfig", "OllamaConfig"]

namel3ss/config/dotenv.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_dotenv_for_path(ai_path: str) -> dict[str, str]:
+    path = Path(ai_path).resolve()
+    env_path = path.parent / ".env"
+    if not env_path.exists():
+        return {}
+    values: dict[str, str] = {}
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if "=" not in stripped:
+            continue
+        key, raw_value = stripped.split("=", 1)
+        key = key.strip()
+        value = raw_value.strip().strip('"').strip("'")
+        if key:
+            values[key] = value
+    return values
+
+
+def apply_dotenv(values: dict[str, str]) -> None:
+    for key, value in values.items():
+        if key not in os.environ:
+            os.environ[key] = value
+
+
+__all__ = ["load_dotenv_for_path", "apply_dotenv"]

namel3ss/config/loader.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from namel3ss.config.model import AppConfig
+from namel3ss.errors.base import Namel3ssError
+
+
+CONFIG_PATH = Path.home() / ".namel3ss" / "config.json"
+
+
+def load_config(config_path: Path | None = None) -> AppConfig:
+    config = AppConfig()
+    path = config_path or CONFIG_PATH
+    if path.exists():
+        _apply_file_config(config, path)
+    _apply_env_overrides(config)
+    return config
+
+
+def _apply_file_config(config: AppConfig, path: Path) -> None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as err:
+        raise Namel3ssError(f"Invalid config file at {path}: {err}") from err
+    if not isinstance(data, dict):
+        raise Namel3ssError(f"Config file must contain an object at {path}")
+    ollama_cfg = data.get("ollama", {})
+    if isinstance(ollama_cfg, dict):
+        if "host" in ollama_cfg:
+            config.ollama.host = str(ollama_cfg["host"])
+        if "timeout_seconds" in ollama_cfg:
+            try:
+                config.ollama.timeout_seconds = int(ollama_cfg["timeout_seconds"])
+            except (TypeError, ValueError) as err:
+                raise Namel3ssError("ollama.timeout_seconds must be an integer") from err
+    openai_cfg = data.get("openai", {})
+    if isinstance(openai_cfg, dict):
+        if "api_key" in openai_cfg:
+            config.openai.api_key = str(openai_cfg["api_key"])
+        if "base_url" in openai_cfg:
+            config.openai.base_url = str(openai_cfg["base_url"])
+    anthropic_cfg = data.get("anthropic", {})
+    if isinstance(anthropic_cfg, dict) and "api_key" in anthropic_cfg:
+        config.anthropic.api_key = str(anthropic_cfg["api_key"])
+    gemini_cfg = data.get("gemini", {})
+    if isinstance(gemini_cfg, dict) and "api_key" in gemini_cfg:
+        config.gemini.api_key = str(gemini_cfg["api_key"])
+    mistral_cfg = data.get("mistral", {})
+    if isinstance(mistral_cfg, dict) and "api_key" in mistral_cfg:
+        config.mistral.api_key = str(mistral_cfg["api_key"])
+
+
+def _apply_env_overrides(config: AppConfig) -> None:
+    host = os.getenv("NAMEL3SS_OLLAMA_HOST")
+    if host:
+        config.ollama.host = host
+    timeout = os.getenv("NAMEL3SS_OLLAMA_TIMEOUT_SECONDS")
+    if timeout:
+        try:
+            config.ollama.timeout_seconds = int(timeout)
+        except ValueError as err:
+            raise Namel3ssError("NAMEL3SS_OLLAMA_TIMEOUT_SECONDS must be an integer") from err
+    api_key = os.getenv("NAMEL3SS_OPENAI_API_KEY")
+    if api_key:
+        config.openai.api_key = api_key
+    base_url = os.getenv("NAMEL3SS_OPENAI_BASE_URL")
+    if base_url:
+        config.openai.base_url = base_url
+    anthropic_key = os.getenv("NAMEL3SS_ANTHROPIC_API_KEY")
+    if anthropic_key:
+        config.anthropic.api_key = anthropic_key
+    gemini_key = os.getenv("NAMEL3SS_GEMINI_API_KEY")
+    if gemini_key:
+        config.gemini.api_key = gemini_key
+    mistral_key = os.getenv("NAMEL3SS_MISTRAL_API_KEY")
+    if mistral_key:
+        config.mistral.api_key = mistral_key
+
+
+__all__ = ["load_config", "CONFIG_PATH"]

namel3ss/config/model.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class OllamaConfig:
+    host: str = "http://127.0.0.1:11434"
+    timeout_seconds: int = 30
+
+
+@dataclass
+class OpenAIConfig:
+    api_key: str | None = None
+    base_url: str = "https://api.openai.com"
+
+
+@dataclass
+class AnthropicConfig:
+    api_key: str | None = None
+
+
+@dataclass
+class GeminiConfig:
+    api_key: str | None = None
+
+
+@dataclass
+class MistralConfig:
+    api_key: str | None = None
+
+
+@dataclass
+class AppConfig:
+    ollama: OllamaConfig = field(default_factory=OllamaConfig)
+    openai: OpenAIConfig = field(default_factory=OpenAIConfig)
+    anthropic: AnthropicConfig = field(default_factory=AnthropicConfig)
+    gemini: GeminiConfig = field(default_factory=GeminiConfig)
+    mistral: MistralConfig = field(default_factory=MistralConfig)
+
+
+__all__ = [
+    "AppConfig",
+    "OllamaConfig",
+    "OpenAIConfig",
+    "AnthropicConfig",
+    "GeminiConfig",
+    "MistralConfig",
+]

namel3ss/errors/__init__.py

@@ -0,0 +1,2 @@
+"""Shared error types and helpers."""
+

namel3ss/errors/base.py

@@ -0,0 +1,34 @@
+"""
+Shared error types for Namel3ss.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Namel3ssError(Exception):
+    """Base error with optional source location."""
+
+    message: str
+    line: Optional[int] = None
+    column: Optional[int] = None
+    end_line: Optional[int] = None
+    end_column: Optional[int] = None
+
+    def __str__(self) -> str:
+        location = self._format_location()
+        return f"{location}{self.message}" if location else self.message
+
+    def _format_location(self) -> str:
+        if self.line is None:
+            return ""
+        if self.end_line is None or self.end_column is None:
+            return f"[line {self.line}, col {self.column or 1}] "
+        return (
+            f"[line {self.line}, col {self.column or 1} - "
+            f"line {self.end_line}, col {self.end_column}] "
+        )
+

namel3ss/errors/render.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def format_error(err: Namel3ssError, source: Optional[str] = None) -> str:
+    base = str(err)
+    if source is None or err.line is None:
+        return base
+
+    lines = source.splitlines()
+    line_index = err.line - 1
+    if line_index < 0 or line_index >= len(lines):
+        return base
+
+    line_text = lines[line_index]
+    column = err.column if err.column is not None else 1
+    caret_pos = max(1, min(column, len(line_text) + 1))
+    caret_line = " " * (caret_pos - 1) + "^"
+    return f"{base}\n{line_text}\n{caret_line}"

namel3ss/format/__init__.py

@@ -0,0 +1,3 @@
+from namel3ss.format.formatter import format_source
+
+__all__ = ["format_source"]

namel3ss/format/formatter.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from namel3ss.format.rules import collapse_blank_lines, migrate_buttons, normalize_indentation, normalize_spacing
+
+
+def format_source(source: str) -> str:
+    lines = source.splitlines()
+    lines = [line.rstrip() for line in lines]
+    lines = migrate_buttons(lines)
+    lines = [normalize_spacing(line) for line in lines]
+    lines = normalize_indentation(lines)
+    lines = collapse_blank_lines(lines)
+    formatted = "\n".join(lines)
+    if formatted and not formatted.endswith("\n"):
+        formatted += "\n"
+    if not formatted and source.endswith("\n"):
+        formatted = "\n"
+    return formatted