namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/studio/server.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import os
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.studio.api import (
+    apply_edit,
+    execute_action,
+    get_actions_payload,
+    get_lint_payload,
+    get_summary_payload,
+    get_ui_payload,
+)
+from namel3ss.studio.session import SessionState
+
+
+class StudioRequestHandler(SimpleHTTPRequestHandler):
+    def log_message(self, format: str, *args: Any) -> None:  # pragma: no cover - silence
+        pass
+
+    def _read_source(self) -> str:
+        path = Path(self.server.app_path)  # type: ignore[attr-defined]
+        return path.read_text(encoding="utf-8")
+
+    def _get_session(self) -> SessionState:
+        return self.server.session_state  # type: ignore[attr-defined]
+
+    def _respond_json(self, payload: dict, status: int = 200) -> None:
+        data = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path.startswith("/api/"):
+            self.handle_api()
+            return
+        self.handle_static()
+
+    def do_POST(self) -> None:  # noqa: N802
+        if self.path.startswith("/api/"):
+            self.handle_api_post()
+            return
+        self.send_error(404)
+
+    def handle_static(self) -> None:
+        web_root = Path(__file__).parent / "web"
+        if self.path in {"/", "/index.html"}:
+            file_path = web_root / "index.html"
+        else:
+            file_path = web_root / self.path.lstrip("/")
+        if not file_path.exists():
+            self.send_error(404)
+            return
+        content = file_path.read_bytes()
+        content_type = "text/html"
+        if file_path.suffix == ".js":
+            content_type = "application/javascript"
+        if file_path.suffix == ".css":
+            content_type = "text/css"
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def handle_api(self) -> None:
+        try:
+            source = self._read_source()
+        except Exception as err:  # pragma: no cover - IO error edge
+            payload = {"ok": False, "error": f"Cannot read source: {err}"}
+            self._respond_json(payload, status=500)
+            return
+        if self.path == "/api/summary":
+            payload = get_summary_payload(source, self.server.app_path)  # type: ignore[attr-defined]
+            status = 200 if payload.get("ok") else 400
+            self._respond_json(payload, status=status)
+            return
+        if self.path == "/api/ui":
+            payload = get_ui_payload(source, self._get_session())
+            status = 200 if payload.get("ok", True) else 400
+            self._respond_json(payload, status=status)
+            return
+        if self.path == "/api/actions":
+            payload = get_actions_payload(source)
+            status = 200 if payload.get("ok") else 400
+            self._respond_json(payload, status=status)
+            return
+        if self.path == "/api/lint":
+            payload = get_lint_payload(source)
+            self._respond_json(payload, status=200)
+            return
+        self.send_error(404)
+
+    def handle_api_post(self) -> None:
+        length = int(self.headers.get("Content-Length", "0"))
+        raw_body = self.rfile.read(length) if length else b""
+        try:
+            body = json.loads(raw_body.decode("utf-8") or "{}")
+        except json.JSONDecodeError:
+            self._respond_json({"ok": False, "error": "Invalid JSON body"}, status=400)
+            return
+        try:
+            source = self._read_source()
+        except Exception as err:  # pragma: no cover
+            payload = {"ok": False, "error": f"Cannot read source: {err}"}
+            self._respond_json(payload, status=500)
+            return
+        if self.path == "/api/edit":
+            if not isinstance(body, dict):
+                self._respond_json({"ok": False, "error": "Body must be a JSON object"}, status=400)
+                return
+            op = body.get("op")
+            target = body.get("target")
+            value = body.get("value", "")
+            if not isinstance(op, str):
+                self._respond_json({"ok": False, "error": "Edit op is required"}, status=400)
+                return
+            if not isinstance(target, dict):
+                self._respond_json({"ok": False, "error": "Edit target is required"}, status=400)
+                return
+            if not isinstance(value, str):
+                self._respond_json({"ok": False, "error": "Edit value must be a string"}, status=400)
+                return
+            try:
+                resp = apply_edit(self.server.app_path, op, target, value, self._get_session())  # type: ignore[attr-defined]
+                self._respond_json(resp, status=200)
+                return
+            except Namel3ssError as err:
+                self._respond_json({"ok": False, "error": format_error(err, source)}, status=400)
+                return
+        if self.path == "/api/action":
+            if not isinstance(body, dict):
+                self._respond_json({"ok": False, "error": "Body must be a JSON object"}, status=400)
+                return
+            action_id = body.get("id")
+            payload = body.get("payload") or {}
+            if not isinstance(action_id, str):
+                self._respond_json({"ok": False, "error": "Action id is required"}, status=400)
+                return
+            if not isinstance(payload, dict):
+                self._respond_json({"ok": False, "error": "Payload must be an object"}, status=400)
+                return
+            try:
+                resp = execute_action(source, self._get_session(), action_id, payload)
+                status = 200 if resp.get("ok", True) else 200
+                self._respond_json(resp, status=status)
+                return
+            except Namel3ssError as err:
+                self._respond_json({"ok": False, "error": format_error(err, source)}, status=400)
+                return
+        if self.path == "/api/reset":
+            self.server.session_state = SessionState()  # type: ignore[attr-defined]
+            self._respond_json({"ok": True}, status=200)
+            return
+        self.send_error(404)
+
+
+def start_server(app_path: str, port: int) -> None:
+    handler = StudioRequestHandler
+    server = HTTPServer(("127.0.0.1", port), handler)
+    server.app_path = app_path  # type: ignore[attr-defined]
+    server.session_state = SessionState()  # type: ignore[attr-defined]
+    print(f"Studio: http://127.0.0.1:{port}/")
+    try:
+        server.serve_forever()
+    finally:
+        server.server_close()

namel3ss/studio/session.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from namel3ss.runtime.store.memory_store import MemoryStore
+
+
+@dataclass
+class SessionState:
+    state: dict = field(default_factory=dict)
+    store: MemoryStore = field(default_factory=MemoryStore)

namel3ss/studio/web/app.js

@@ -0,0 +1,248 @@
+async function fetchJson(path, options) {
+  const res = await fetch(path, options);
+  return res.json();
+}
+
+function renderSummary(data) {
+  const el = document.getElementById("summary");
+  if (!data.ok) {
+    el.textContent = data.error || "Error";
+    return;
+  }
+  el.textContent = JSON.stringify(data.counts, null, 2);
+}
+
+function renderActions(data) {
+  const el = document.getElementById("actions");
+  if (!data.ok) {
+    el.textContent = data.error || "Error";
+    return;
+  }
+  el.textContent = data.actions
+    .map((a) => {
+      const parts = [a.id, a.type];
+      if (a.flow) parts.push(`flow=${a.flow}`);
+      if (a.record) parts.push(`record=${a.record}`);
+      return parts.join("  ");
+    })
+    .join("\n");
+}
+
+function renderLint(data) {
+  const el = document.getElementById("lint");
+  if (!data.ok && data.error) {
+    el.textContent = data.error;
+    return;
+  }
+  el.textContent =
+    data.findings
+      .map((f) => `${f.severity} ${f.code} ${f.message} (${f.line}:${f.column})`)
+      .join("\n") || "OK";
+}
+
+function renderState(data) {
+  const el = document.getElementById("state");
+  el.textContent = data ? JSON.stringify(data, null, 2) : "{}";
+}
+
+function renderTraces(data) {
+  const el = document.getElementById("traces");
+  el.textContent = data ? JSON.stringify(data, null, 2) : "[]";
+}
+
+async function executeAction(actionId, payload) {
+  const res = await fetch("/api/action", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ id: actionId, payload }),
+  });
+  const data = await res.json();
+  if (!data.ok && data.error) {
+    alert(data.error);
+  }
+  if (!data.ok && data.errors) {
+    return data;
+  }
+  if (data.state) {
+    renderState(data.state);
+  }
+  if (data.traces) {
+    renderTraces(data.traces);
+  }
+  if (data.ui) {
+    renderUI(data.ui);
+  }
+  return data;
+}
+
+async function performEdit(op, elementId, pageName, value) {
+  const res = await fetch("/api/edit", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ op, target: { element_id: elementId, page: pageName }, value }),
+  });
+  const data = await res.json();
+  if (!data.ok) {
+    alert(data.error || "Edit failed");
+    return;
+  }
+  renderSummary(data.summary);
+  renderActions(data.actions);
+  renderLint(data.lint);
+  if (data.ui) {
+    renderUI(data.ui);
+  }
+}
+
+function renderUI(manifest) {
+  const select = document.getElementById("pageSelect");
+  const uiContainer = document.getElementById("ui");
+  const pages = manifest.pages || [];
+  const currentSelection = select.value;
+  select.innerHTML = "";
+  pages.forEach((p, idx) => {
+    const opt = document.createElement("option");
+    opt.value = p.name;
+    opt.textContent = p.name;
+    if (p.name === currentSelection || (currentSelection === "" && idx === 0)) {
+      opt.selected = true;
+    }
+    select.appendChild(opt);
+  });
+
+  function renderPage(pageName) {
+    uiContainer.innerHTML = "";
+    const page = pages.find((p) => p.name === pageName) || pages[0];
+    if (!page) return;
+    page.elements.forEach((el) => {
+      const div = document.createElement("div");
+      div.className = "element";
+      if (el.type === "title") {
+        const h = document.createElement("h3");
+        h.textContent = el.value;
+        div.appendChild(h);
+        const btn = document.createElement("button");
+        btn.textContent = "Edit";
+        btn.onclick = () => showEditField(el, page.name, "set_title");
+        div.appendChild(btn);
+      } else if (el.type === "text") {
+        const p = document.createElement("p");
+        p.textContent = el.value;
+        div.appendChild(p);
+        const btn = document.createElement("button");
+        btn.textContent = "Edit";
+        btn.onclick = () => showEditField(el, page.name, "set_text");
+        div.appendChild(btn);
+      } else if (el.type === "button") {
+        const btn = document.createElement("button");
+        btn.textContent = el.label;
+        btn.onclick = () => executeAction(el.action_id, {});
+        div.appendChild(btn);
+        const rename = document.createElement("button");
+        rename.textContent = "Rename";
+        rename.onclick = () => showEditField(el, page.name, "set_button_label");
+        div.appendChild(rename);
+      } else if (el.type === "form") {
+        const form = document.createElement("form");
+        form.innerHTML = `<strong>Form: ${el.record}</strong>`;
+        (el.fields || []).forEach((f) => {
+          const label = document.createElement("label");
+          label.textContent = f.name;
+          const input = document.createElement("input");
+          input.name = f.name;
+          label.appendChild(input);
+          form.appendChild(label);
+        });
+        const submit = document.createElement("button");
+        submit.type = "submit";
+        submit.textContent = "Submit";
+        form.appendChild(submit);
+        const errors = document.createElement("div");
+        errors.className = "errors";
+        form.appendChild(errors);
+        form.onsubmit = async (e) => {
+          e.preventDefault();
+          const values = {};
+          (el.fields || []).forEach((f) => {
+            const input = form.querySelector(`input[name="${f.name}"]`);
+            values[f.name] = input ? input.value : "";
+          });
+          const result = await executeAction(el.action_id, { values });
+          if (!result.ok && result.errors) {
+            errors.textContent = result.errors.map((err) => `${err.field}: ${err.message}`).join("; ");
+          } else if (!result.ok && result.error) {
+            errors.textContent = result.error;
+          } else {
+            errors.textContent = "";
+          }
+        };
+        div.appendChild(form);
+      } else if (el.type === "table") {
+        const table = document.createElement("table");
+        const header = document.createElement("tr");
+        (el.columns || []).forEach((c) => {
+          const th = document.createElement("th");
+          th.textContent = c.name;
+          header.appendChild(th);
+        });
+        table.appendChild(header);
+        (el.rows || []).forEach((row) => {
+          const tr = document.createElement("tr");
+          (el.columns || []).forEach((c) => {
+            const td = document.createElement("td");
+            td.textContent = row[c.name] ?? "";
+            tr.appendChild(td);
+          });
+          table.appendChild(tr);
+        });
+        div.appendChild(table);
+      }
+      uiContainer.appendChild(div);
+    });
+  }
+
+  select.onchange = (e) => renderPage(e.target.value);
+  const initialPage = select.value || (pages[0] ? pages[0].name : "");
+  if (initialPage) {
+    renderPage(initialPage);
+  } else {
+    uiContainer.textContent = "No pages";
+  }
+}
+
+function showEditField(element, pageName, op) {
+  const newValue = prompt("Enter new value", element.value || element.label || "");
+  if (newValue === null) {
+    return;
+  }
+  performEdit(op, element.element_id, pageName, newValue);
+}
+
+async function refreshAll() {
+  const [summary, ui, actions, lint] = await Promise.all([
+    fetchJson("/api/summary"),
+    fetchJson("/api/ui"),
+    fetchJson("/api/actions"),
+    fetchJson("/api/lint"),
+  ]);
+  renderSummary(summary);
+  renderActions(actions);
+  renderLint(lint);
+  renderState({});
+  renderTraces([]);
+  if (ui.ok !== false) {
+    renderUI(ui);
+  } else {
+    document.getElementById("ui").textContent = ui.error || "Error";
+  }
+}
+
+document.getElementById("refresh").onclick = refreshAll;
+document.getElementById("reset").onclick = async () => {
+  await fetch("/api/reset", { method: "POST", body: "{}" });
+  renderState({});
+  renderTraces([]);
+  refreshAll();
+};
+
+refreshAll();

namel3ss/studio/web/index.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Namel3ss Studio</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <header>
+    <h1>Namel3ss Studio</h1>
+    <button id="refresh">Refresh</button>
+    <button id="reset">Reset</button>
+  </header>
+  <main>
+    <section>
+      <h2>Summary</h2>
+      <pre id="summary"></pre>
+    </section>
+    <section>
+      <h2>UI Preview</h2>
+      <select id="pageSelect"></select>
+      <div id="ui"></div>
+    </section>
+    <section>
+      <h2>State</h2>
+      <pre id="state"></pre>
+    </section>
+    <section>
+      <h2>Traces</h2>
+      <pre id="traces"></pre>
+    </section>
+    <section>
+      <h2>Actions</h2>
+      <pre id="actions"></pre>
+    </section>
+    <section>
+      <h2>Lint Findings</h2>
+      <pre id="lint"></pre>
+    </section>
+  </main>
+  <script src="/app.js"></script>
+</body>
+</html>

namel3ss/studio/web/styles.css

@@ -0,0 +1,42 @@
+body {
+  font-family: Arial, sans-serif;
+  margin: 0;
+  padding: 0 16px 32px 16px;
+}
+
+header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  border-bottom: 1px solid #ddd;
+  padding: 12px 0;
+}
+
+main {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 16px;
+  margin-top: 16px;
+}
+
+section {
+  border: 1px solid #eee;
+  padding: 12px;
+  border-radius: 6px;
+  background: #fafafa;
+}
+
+pre {
+  background: #fff;
+  border: 1px solid #eee;
+  padding: 8px;
+  overflow: auto;
+}
+
+.element {
+  margin-bottom: 8px;
+}
+
+button {
+  padding: 6px 12px;
+}

namel3ss/templates/__init__.py

@@ -0,0 +1,3 @@
+"""Project templates for `n3 new`."""
+
+__all__ = []

namel3ss/templates/ai_assistant/.gitignore

@@ -0,0 +1 @@
+.env

namel3ss/templates/ai_assistant/README.md

@@ -0,0 +1,10 @@
+# {{PROJECT_NAME}} (AI Assistant)
+
+Ask an AI assistant over saved notes. Includes an echo tool, memory config, and a notes page with a call-to-action button.
+
+Run it with:
+- `n3 app.ai check`
+- `n3 app.ai studio`
+- `n3 app.ai actions`
+
+Put any API keys in a local `.env` (not committed).

namel3ss/templates/ai_assistant/app.ai

@@ -0,0 +1,30 @@
+tool "echo":
+  kind is "builtin"
+
+record "Note":
+  title string must be present
+  body string must be present
+
+ai "assistant":
+  model is "gpt-4.1"
+  system_prompt is "You are a helpful assistant for {{PROJECT_NAME}}."
+  tools:
+    expose "echo"
+  memory:
+    short_term is 5
+    semantic is true
+    profile is true
+
+flow "ask_assistant":
+  let prompt is "Summarize the latest notes."
+  ask ai "assistant" with input: prompt as reply
+  set state.reply is reply
+  return reply
+
+page "notes":
+  title is "{{PROJECT_NAME}} Notes Assistant"
+  text is "Save notes and ask the assistant for help."
+  form is "Note"
+  table is "Note"
+  button "Ask assistant":
+    calls flow "ask_assistant"

namel3ss/templates/crud/.gitignore

@@ -0,0 +1 @@
+.env

namel3ss/templates/crud/README.md

@@ -0,0 +1,10 @@
+# {{PROJECT_NAME}} (CRUD)
+
+Starter CRUD dashboard with a customer record, seed flow, and a combined form/table page.
+
+Run it with:
+- `n3 app.ai check`
+- `n3 app.ai studio`
+- `n3 app.ai actions`
+
+Put any API keys in a local `.env` (not committed).

namel3ss/templates/crud/app.ai

@@ -0,0 +1,26 @@
+record "Customer":
+  name string must be present
+  email string must match pattern ".*@.*"
+  age int must be greater than 17
+
+flow "seed_customers":
+  set state.customer.name is "Alice"
+  set state.customer.email is "alice@example.com"
+  set state.customer.age is 21
+  save Customer
+  set state.customer.name is "Bob"
+  set state.customer.email is "bob@example.com"
+  set state.customer.age is 30
+  save Customer
+  return "seeded"
+
+flow "hello":
+  return "Hello from {{PROJECT_NAME}}"
+
+page "home":
+  title is "{{PROJECT_NAME}} Dashboard"
+  text is "Add customers and view them below."
+  button "Seed demo data":
+    calls flow "seed_customers"
+  form is "Customer"
+  table is "Customer"

namel3ss/templates/multi_agent/.gitignore

@@ -0,0 +1 @@
+.env

namel3ss/templates/multi_agent/README.md

@@ -0,0 +1,10 @@
+# {{PROJECT_NAME}} (Multi-Agent)
+
+Planner, critic, and researcher agents collaborating on a shared assistant with a single workflow page.
+
+Run it with:
+- `n3 app.ai check`
+- `n3 app.ai studio`
+- `n3 app.ai actions`
+
+Put any API keys in a local `.env` (not committed).

namel3ss/templates/multi_agent/app.ai

@@ -0,0 +1,43 @@
+tool "echo":
+  kind is "builtin"
+
+ai "assistant":
+  model is "gpt-4.1"
+  system_prompt is "You are a helpful multi-agent assistant for {{PROJECT_NAME}}."
+  tools:
+    expose "echo"
+  memory:
+    short_term is 5
+    semantic is true
+    profile is true
+
+agent "planner":
+  ai is "assistant"
+  system_prompt is "Plan step-by-step."
+
+agent "critic":
+  ai is "assistant"
+  system_prompt is "Find risks and gaps."
+
+agent "researcher":
+  ai is "assistant"
+  system_prompt is "Add supporting details."
+
+flow "run_workflow":
+  let task is "Plan a 3-step launch checklist for {{PROJECT_NAME}}"
+  run agent "planner" with input: task as plan
+  run agents in parallel:
+    agent "critic" with input: plan
+    agent "researcher" with input: plan
+  as feedback
+  ask ai "assistant" with input: plan as final
+  set state.plan is plan
+  set state.feedback is feedback
+  set state.final is final
+  return final
+
+page "workflow":
+  title is "{{PROJECT_NAME}} Multi-Agent Workflow"
+  text is "Planner plus critic and researcher."
+  button "Run workflow":
+    calls flow "run_workflow"

namel3ss/ui/__init__.py

@@ -0,0 +1,2 @@
+"""UI utilities for Namel3ss."""
+