jac-coder 0.1.0__py3-none-any.whl

jac_coder/data/reference/ai.md

@@ -0,0 +1,131 @@
+# AI Integration — by llm()
+
+## Required Setup — byllm Import
+
+**You MUST import byllm and create a glob model before using any `by llm()` call.**
+
+```jac
+import from byllm.lib { Model }
+
+glob llm: Model = Model(model_name="gpt-4o");
+```
+
+Without this, `by llm()` will fail. The glob variable name (e.g. `llm`, `model`) is what you reference in `by llm()` or `by model()`.
+
+## Simple LLM Functions
+
+The `by llm()` suffix turns a function into an LLM call. The LLM infers behavior from the function name, parameter names, types, and return type.
+
+```jac
+import from byllm.lib { Model }
+
+glob llm: Model = Model(model_name="gpt-4o");
+
+# Simple classification — LLM figures it out from name + types
+def classify_sentiment(text: str) -> str by llm();
+
+# With explicit reasoning
+def classify(message: str) -> str by llm(method="Reason", temperature=0.1);
+
+# Enum return type for constrained output
+enum Sentiment { POSITIVE, NEGATIVE, NEUTRAL }
+def analyze(text: str) -> Sentiment by llm();
+```
+
+## Semantic Annotations
+
+`sem` annotations provide system prompts for `by llm()` functions.
+
+```jac
+# On methods
+sem MyAgent.respond = """You are an expert coding agent.
+Use tools to read, write, and test code.""";
+
+# On fields (describes what the field means to the LLM)
+sem ReviewResult.is_approved = "True if content meets quality standards";
+```
+
+## ReAct Agent with Tools
+
+Passing `tools=` auto-triggers ReAct (reason-act) loop.
+
+```jac
+def respond(message: str, chat_history: list[dict]) -> str by llm(
+    messages=chat_history,
+    tools=[read_file, search, bash_exec],
+    incl_info={"reference": knowledge_base},
+    max_react_iterations=10,
+    temperature=0.2,
+    stream=True
+);
+```
+
+## LLM-Driven Graph Traversal
+
+The LLM can decide which node to visit next:
+
+```jac
+# LLM picks child node based on context
+can route with Router entry {
+    visit [-->] by llm(
+        incl_info={"message": self.message, "context": self.context}
+    );
+}
+```
+
+## Model Configuration
+
+```jac
+import from byllm.lib { Model }
+
+glob model: Model = Model(model_name="openai/gpt-4o-mini");
+
+# Use specific model for a function
+def summarize(text: str) -> str by model(
+    reason="Summarize in 2-3 sentences"
+);
+```
+
+## Interface/Implementation with LLM
+
+Declaration file:
+```jac
+node Router {
+    def classify(message: str) -> str by llm(method="Reason");
+}
+```
+
+Implementation file:
+```jac
+sem Router.classify = """Return exactly one label: BUILD, PLAN, or EXPLORE.""";
+```
+
+## Full Agent Example
+
+```jac
+node Router {}
+node QAHandler {
+    def respond(message: str, context: list[dict]) -> str by llm(
+        method="Reason", messages=context, temperature=0.3
+    );
+    can handle with process_request entry;
+}
+
+walker :pub process_request {
+    has message: str;
+    has context: list[dict] = [];
+
+    can route with Router entry {
+        visit [-->] by llm(
+            incl_info={"message": self.message}
+        );
+    }
+    can init_graph with Root entry {
+        visit [-->][?:Router] else {
+            router = (here ++> Router())[0];
+            router ++> QAHandler();
+            visit router;
+        };
+    }
+}
+```

jac_coder/data/reference/backend.md

@@ -0,0 +1,215 @@
+# Backend Development — Endpoints, Persistence, Auth
+
+## Function Endpoints (def:pub / def:priv)
+
+Simple CRUD — preferred for most use cases.
+
+```jac
+import from uuid { uuid4 }
+import from datetime { datetime }
+
+node Todo {
+    has id: str = "";
+    has title: str = "";
+    has completed: bool = False;
+    has created_at: str = "";
+}
+
+def:pub get_todos() -> list {
+    return [{"id": t.id, "title": t.title, "completed": t.completed}
+            for t in [root-->][?:Todo]];
+}
+
+def:pub add_todo(title: str) -> dict {
+    todo = (root ++> Todo(
+        id=str(uuid4()), title=title,
+        created_at=str(datetime.now())
+    ))[0];
+    return {"id": todo.id, "title": todo.title, "completed": False};
+}
+
+def:pub toggle_todo(id: str) -> dict {
+    for todo in [root-->][?:Todo] {
+        if todo.id == id {
+            todo.completed = not todo.completed;
+            return {"id": todo.id, "completed": todo.completed};
+        }
+    }
+    return {"error": "not found"};
+}
+
+def:pub delete_todo(id: str) -> dict {
+    for todo in [root-->][?:Todo] {
+        if todo.id == id {
+            del todo;
+            return {"deleted": id};
+        }
+    }
+    return {"error": "not found"};
+}
+```
+
+## Walker Endpoints
+
+For graph traversal and multi-step operations:
+
+```jac
+walker :pub get_post_with_comments {
+    has post_id: str = "";
+
+    can find_post with Root entry {
+        for p in [-->][?:Post] {
+            if p.id == self.post_id { visit p; return; }
+        }
+        report {"error": "not found"};
+    }
+
+    can collect with Post entry {
+        comments = [{"id": c.id, "text": c.text}
+                    for c in [-->][?:Comment]];
+        report {
+            "post": {"id": here.id, "title": here.title},
+            "comments": comments
+        };
+    }
+}
+```
+
+## Data Persistence
+
+- Nodes connected to `root` **auto-persist** across requests (SQLite)
+- No database setup needed — the language handles it
+- `del node;` removes from graph and storage
+
+```jac
+# Create + persist
+root ++> Todo(id=str(uuid4()), title="Buy milk");
+
+# Query all
+todos = [root-->][?:Todo];
+
+# Query with filter
+found = [root-->][?:Todo](?title == "Buy milk");
+
+# Delete
+root del--> todo;
+# or: del todo;
+```
+
+## Per-User Data Isolation (def:priv)
+
+`:priv` endpoints require authentication. Each user gets their own isolated `root`.
+
+```jac
+# Public — shared root, anyone can call
+def:pub get_shared_data() -> list {
+    return [{"id": str(d.id)} for d in [root-->][?:DataNode]];
+}
+
+# Private — per-user root, requires login
+def:priv get_my_tasks() -> list {
+    return [{"id": t.id, "title": t.title}
+            for t in [root-->][?:Task]];
+}
+```
+
+## Authentication
+
+Built-in auth functions for fullstack apps:
+
+```jac
+cl import from "@jac/runtime" { jacLogin, jacSignup, jacLogout, jacIsLoggedIn }
+```
+
+| Function | Returns | Purpose |
+|----------|---------|---------|
+| `jacLogin(username, password)` | `bool` | Log in, stores token |
+| `jacSignup(username, password)` | `dict` (has `.success`) | Register user |
+| `jacLogout()` | `void` | Clear auth token |
+| `jacIsLoggedIn()` | `bool` | Check valid token |
+
+## File-Based Routing
+
+```
+pages/
+├── layout.jac              # Root layout with <Outlet />
+├── index.jac               # Route: /
+├── about.jac               # Route: /about
+├── users/
+│   ├── index.jac           # Route: /users
+│   └── [id].jac            # Route: /users/:id (dynamic)
+├── (public)/               # Route group (no URL segment)
+│   └── login.jac           # Route: /login
+├── (auth)/                 # Protected group
+│   ├── layout.jac          # AuthGuard layout
+│   └── dashboard.jac       # Route: /dashboard
+└── [...notFound].jac       # Catch-all 404
+```
+
+### Layout with Outlet
+
+```jac
+# pages/layout.jac
+cl import from "@jac/runtime" { Outlet, Link }
+
+cl {
+    def:pub layout() -> JsxElement {
+        return <>
+            <nav>
+                <Link to="/">Home</Link>
+                <Link to="/about">About</Link>
+            </nav>
+            <main><Outlet /></main>
+        </>;
+    }
+}
+```
+
+### Dynamic Routes
+
+```jac
+# pages/users/[id].jac
+cl import from "@jac/runtime" { useParams }
+
+cl {
+    def:pub page() -> JsxElement {
+        params = useParams();
+        return <div>User: {params.id}</div>;
+    }
+}
+```
+
+### Protected Routes
+
+```jac
+# pages/(auth)/layout.jac
+cl import from "@jac/runtime" { AuthGuard, Outlet }
+
+cl {
+    def:pub layout() -> JsxElement {
+        return <AuthGuard redirect="/login"><Outlet /></AuthGuard>;
+    }
+}
+```
+
+### Navigation
+
+```jac
+cl import from "@jac/runtime" { useNavigate, Link }
+
+navigate = useNavigate();
+navigate("/path");                    # Push
+navigate("/path", {"replace": True}); # Replace
+navigate(-1);                          # Back
+
+<Link to="/about">About</Link>
+```
+
+## Running a Fullstack App
+
+```bash
+jac start --dev    # Dev: Vite on :8000, API on :8001
+jac start          # Production: single server on :8000
+```
+
+Visit `http://localhost:8000/docs` for Swagger UI.

jac_coder/data/reference/frontend.md

@@ -0,0 +1,271 @@
+# Frontend Components — .cl.jac
+
+## Component Definition
+
+Components are public functions returning `JsxElement`.
+
+```jac
+def:pub Header(props: dict) -> JsxElement {
+    title = props.title or "";
+    return (
+        <header className="border-b px-6 py-4">
+            <h1 className="text-xl font-bold">{title}</h1>
+        </header>
+    );
+}
+```
+
+Components need `def:pub` to be importable by other files.
+
+## State Management
+
+`has` inside a component function auto-generates `useState`.
+
+```jac
+def:pub Counter() -> JsxElement {
+    has count: int = 0;
+    has name: str = "";
+    has items: list = [];
+
+    # Assignment triggers re-render (calls setter internally)
+    count = count + 1;
+    items = items + [newItem];    # new reference = re-render
+}
+```
+
+- NEVER define `setX` yourself — it already exists from `has`
+- NEVER use `.append()` — it mutates in place (no re-render)
+- Always init with correct type, NEVER `None` or `any`
+
+## Effects (Lifecycle)
+
+```jac
+can with entry { ... }                  # Mount (useEffect with [])
+async can with entry { ... }            # Async mount
+can with [dep1, dep2] entry { ... }     # Watch dependencies
+can with (a, b) entry { ... }           # Also dependency watch
+can with exit { ... }                   # Cleanup/unmount
+```
+
+NEVER use `useEffect(lambda...)` — that is OLD syntax.
+
+## Event Handlers
+
+ALL handlers must be named `def` functions defined BEFORE `return`. NEVER use lambda or inline def in JSX.
+
+```jac
+def:pub TodoList() -> JsxElement {
+    has inputValue: str = "";
+
+    # Define handler above return
+    def handle_input(e: any) -> None {
+        inputValue = e.target.value;
+    }
+
+    def handle_submit() -> None {
+        if inputValue { add_item(inputValue); inputValue = ""; }
+    }
+
+    # Pass by name
+    return <div>
+        <input value={inputValue} onChange={handle_input} />
+        <button onClick={handle_submit}>Add</button>
+    </div>;
+}
+```
+
+## List Rendering
+
+Use list comprehension, NEVER `.map()`.
+
+```jac
+# Render list
+{[<TodoItem key={item["id"]} data={item} /> for item in items]}
+
+# With filter
+{[<Tag key={t} label={t} /> for t in tags if t != "hidden"]}
+
+# Add to list (new reference)
+items = items + [newItem];
+
+# Remove from list
+items = [item for item in items if item["id"] != targetId];
+```
+
+## Conditional Rendering
+
+```jac
+{showSidebar and (<Sidebar items={items} />)}
+{isActive and (<ActiveView />) or (<InactiveView />)}
+{(not loading) and (<Content />)}
+```
+
+## Custom Hooks
+
+```jac
+def:pub useCounter(initial: int = 0) -> dict {
+    has count: int = initial;
+    def increment() -> None { count = count + 1; }
+    def decrement() -> None { count = count - 1; }
+    return {"count": count, "increment": increment, "decrement": decrement};
+}
+```
+
+## Data Hook Pattern (sv import + state)
+
+```jac
+# hooks/useTodos.cl.jac
+sv import from ..main { get_todos, add_todo, delete_todo }
+
+def:pub useTodos() -> dict {
+    has todos: list = [];
+    has loading: bool = True;
+    has error: str = "";
+
+    async can with entry {
+        try {
+            result = await get_todos();
+            todos = result or [];
+        } except Exception as e {
+            error = str(e);
+        }
+        loading = False;
+    }
+
+    async def handleAdd(title: str) -> None {
+        if not title { return; }
+        result = await add_todo(title);  # positional args only
+        if result and not result.error {
+            todos = todos + [result];
+        }
+    }
+
+    async def handleDelete(id: str) -> None {
+        result = await delete_todo(id);  # positional args only
+        if result and not result.error {
+            todos = [t for t in todos if t["id"] != id];
+        }
+    }
+
+    return {
+        "todos": todos, "loading": loading, "error": error,
+        "handleAdd": handleAdd, "handleDelete": handleDelete
+    };
+}
+```
+
+## Frontend Import Rules
+
+```jac
+# Same directory (.cl.jac to .cl.jac) — WITH quotes, dots not slashes
+import from ".Header" { Header }
+
+# Parent directory — WITH quotes
+import from "..hooks.useTodos" { useTodos }
+
+# Two levels up — WITH quotes
+import from "...lib.utils" { cn }
+
+# Server calls — sv import, NO quotes
+sv import from ..main { get_todos, add_todo }
+
+# NPM packages — WITH quotes
+import from "clsx" { cn }
+
+# Runtime — cl import, WITH quotes
+cl import from "@jac/runtime" { jacLogin, Outlet }
+
+# CSS — WITH quotes
+import "..styles.global.css";
+```
+
+**Dot levels:** `.` = same dir, `..` = parent, `...` = 2 up
+
+## Calling Backend Walkers
+
+```jac
+sv import from ..main { get_post_details }
+
+async def loadDetails() -> None {
+    result = root spawn get_post_details(post_id=postId);
+    if result and result.reports and len(result.reports) > 0 {
+        data = result.reports[0];
+    }
+}
+```
+
+## Primitive Idioms (Jac, NOT JavaScript)
+
+| JS (WRONG) | Jac (RIGHT) |
+|---|---|
+| `console.log(x)` | `print(x)` |
+| `String(x)` / `.toString()` | `str(x)` |
+| `parseInt(x)` | `int(x)` |
+| `x.length` | `len(x)` |
+| `.toLowerCase()` | `.lower()` |
+| `.toUpperCase()` | `.upper()` |
+| `.trim()` | `.strip()` |
+| `.indexOf(sub)` | `.find(sub)` |
+
+## Inline Styles
+
+```jac
+<div style={{"display": "flex", "gap": "8px", "backgroundColor": "#f0f0f0"}} />
+```
+
+## Service Layer Pattern (for walker calls)
+
+```jac
+# services/apiService.cl.jac
+sv import from ..main { create_item, list_items }
+
+async def:pub createItem(title: str) -> any {
+    try {
+        response = root spawn create_item(title=title);
+        result = response.reports[len(response.reports) - 1]
+            if response.reports and len(response.reports) > 0 else {};
+        return {"success": True, "item": result};
+    } except Exception as e {
+        return {"success": False, "error": str(e)};
+    }
+}
+```
+
+## @jac/runtime — Available Symbols
+
+Use `cl import from "@jac/runtime"` (WITH quotes, WITH `cl` prefix) to import runtime utilities.
+
+### Auth
+```jac
+cl import from "@jac/runtime" { jacLogin, jacSignup, jacLogout, jacIsLoggedIn }
+
+# Usage
+success = await jacLogin(username, password);   # positional args only
+success = await jacSignup(username, password);
+jacLogout();
+is_auth = jacIsLoggedIn();                       # returns bool
+```
+
+### Routing
+```jac
+cl import from "@jac/runtime" { Link, Navigate, useNavigate, Outlet }
+
+# Link — declarative navigation
+<Link to="/dashboard">Go to Dashboard</Link>
+
+# Navigate — redirect component
+if not jacIsLoggedIn() { return <Navigate to="/login" />; }
+
+# useNavigate — programmatic navigation
+navigate = useNavigate();
+def handle_go() -> None { navigate("/dashboard"); }
+
+# Outlet — renders child routes (file-based routing)
+return <div><Outlet /></div>;
+```
+
+### IMPORTANT
+- ALWAYS use `cl import` prefix (not plain `import`)
+- ALWAYS use quotes: `"@jac/runtime"` (it's an npm-style path)
+- NEVER use dots: `@jac.runtime` ← WRONG
+- Auth functions use POSITIONAL args (kwargs broken in .cl.jac)