lambda-erp 0.5.0__tar.gz → 0.6.1__tar.gz

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lambda-erp
-Version: 0.5.0
+Version: 0.6.1
 Summary: Core ERP logic - accounting, sales, purchasing, inventory
 Author: TORUS INVESTMENTS AG
 License-Expression: Apache-2.0
@@ -112,6 +112,7 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 **Key design choices:**
 
 - **Chat-first, not chat-bolted-on.** The chat isn't a copilot sidebar - it's the primary way to interact with the system. Every document type, every report, every master record is reachable from tool-use.
+- **Extensions are first-class to the AI.** A customer deployment registers its own doctypes and master types through plugin seams (`register_doctype`, `register_master`) and the chat discovers them automatically - tool schemas and the system prompt are built per request from the live registries, and fields are introspected from the live table, so there is nothing to teach per type. A CRM lead added by a plugin is searchable in chat from day one, with zero prompt or tool edits.
 - **One shape for every document.** Invoices, sales orders, stock entries, payments - all share a single `Document` base class and the same three-state lifecycle (Draft → Submitted → Cancelled) with `on_submit`/`on_cancel` hooks. The LLM learns the pattern once and drives every doctype the same way. Leading open-source and commercial ERPs have per-model action verbs spread across 150+ core models; each one is a separate tool the model has to get right.
 - **Metadata-driven UI, shared with the LLM.** A single React form component renders every doctype from `frontend/src/lib/doctypes.ts`. The schema the model reasons over and the schema the user sees are literally the same file. Adding a field is two lines - one in the Python class, one in the config - not a new module with hand-written views and inheritance overlays.
 - **Two-model orchestration.** A planner model handles reasoning and tool-use. When it needs to generate code for a custom report, it delegates to a code-specialist sub-agent. This keeps each model doing what it's best at and keeps latency down on simple turns.
@@ -259,10 +260,15 @@ Open `http://localhost:5173`. Vite proxies `/api/*` to the backend.
 OPENAI_API_KEY=sk-...
 ANTHROPIC_API_KEY=sk-ant-...    # optional, used for the code-specialist sub-agent
 ANTHROPIC_CODE_MODEL=claude-opus-4-7   # optional, default shown
+LAMBDA_ERP_ADMIN_EMAIL=admin@example.com   # optional, seeds the admin at boot
+LAMBDA_ERP_ADMIN_PASSWORD=...              # optional, required with the line above
+LAMBDA_ERP_ADMIN_NAME=Administrator        # optional, display name for the seeded admin
 ```
 
 Chat needs `OPENAI_API_KEY`. Custom-report code generation uses `ANTHROPIC_API_KEY` when set; otherwise it falls back and the chat will tell you it can't generate reports.
 
+**Seeded admin.** By default the first person to register becomes the admin. Set `LAMBDA_ERP_ADMIN_EMAIL` + `LAMBDA_ERP_ADMIN_PASSWORD` to instead provision that admin automatically at startup — useful when the database is recreated on every deploy, so a redeployed instance can't be claimed by whoever visits first. It's create-if-missing and idempotent (an existing account with that email is promoted to an enabled admin; its password is left untouched), and the password is only ever read from the environment.
+
 ### Run the validation suite
 
 ```bash
@@ -353,12 +359,13 @@ for side-effects/integrations).
 
 ```python
 # acme/plugin.py
-from api.services import register_doctype, register_converter
+from api.services import register_doctype, register_master, register_converter
 from lambda_erp.hooks import register_hook
 from .sales_invoice import AcmeSalesInvoice
 
 def register():
     register_doctype("Sales Invoice", AcmeSalesInvoice)
+    register_master("gadget", "Gadget", "gadget_name", name_prefix="GAD")
     register_hook("Sales Invoice:after_submit", push_to_external_system)
     # register_converter(source, target, fn)   # only to replace conversion *logic*
 ```
@@ -367,6 +374,14 @@ Point the deployment at it with `LAMBDA_ERP_PLUGINS=acme` (comma-separated for
 several). On startup the core imports each module and calls `register()`. Unset
 = the core runs unchanged.
 
+A `register_master` type (core 0.5.0+) is served at `/api/masters/{slug}` and
+**discovered by the AI chat automatically**: `search_masters` (with fuzzy
+fallback), `get_master_fields`, and `create/update/delete_master` accept it
+from day one. The chat tool schemas and system prompt are built per request
+from the live registries, and fields are introspected from the live table — no
+per-type declarations. Details and caveats:
+[`docs/core-extension-architecture.md`](docs/core-extension-architecture.md).
+
 **Frontend overrides — the `@lambda-development/erp-core` library**
 
 The frontend ships as a library. The customer app depends on it, registers its

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/README.md

@@ -85,6 +85,7 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
 **Key design choices:**
 
 - **Chat-first, not chat-bolted-on.** The chat isn't a copilot sidebar - it's the primary way to interact with the system. Every document type, every report, every master record is reachable from tool-use.
+- **Extensions are first-class to the AI.** A customer deployment registers its own doctypes and master types through plugin seams (`register_doctype`, `register_master`) and the chat discovers them automatically - tool schemas and the system prompt are built per request from the live registries, and fields are introspected from the live table, so there is nothing to teach per type. A CRM lead added by a plugin is searchable in chat from day one, with zero prompt or tool edits.
 - **One shape for every document.** Invoices, sales orders, stock entries, payments - all share a single `Document` base class and the same three-state lifecycle (Draft → Submitted → Cancelled) with `on_submit`/`on_cancel` hooks. The LLM learns the pattern once and drives every doctype the same way. Leading open-source and commercial ERPs have per-model action verbs spread across 150+ core models; each one is a separate tool the model has to get right.
 - **Metadata-driven UI, shared with the LLM.** A single React form component renders every doctype from `frontend/src/lib/doctypes.ts`. The schema the model reasons over and the schema the user sees are literally the same file. Adding a field is two lines - one in the Python class, one in the config - not a new module with hand-written views and inheritance overlays.
 - **Two-model orchestration.** A planner model handles reasoning and tool-use. When it needs to generate code for a custom report, it delegates to a code-specialist sub-agent. This keeps each model doing what it's best at and keeps latency down on simple turns.
@@ -232,10 +233,15 @@ Open `http://localhost:5173`. Vite proxies `/api/*` to the backend.
 OPENAI_API_KEY=sk-...
 ANTHROPIC_API_KEY=sk-ant-...    # optional, used for the code-specialist sub-agent
 ANTHROPIC_CODE_MODEL=claude-opus-4-7   # optional, default shown
+LAMBDA_ERP_ADMIN_EMAIL=admin@example.com   # optional, seeds the admin at boot
+LAMBDA_ERP_ADMIN_PASSWORD=...              # optional, required with the line above
+LAMBDA_ERP_ADMIN_NAME=Administrator        # optional, display name for the seeded admin
 ```
 
 Chat needs `OPENAI_API_KEY`. Custom-report code generation uses `ANTHROPIC_API_KEY` when set; otherwise it falls back and the chat will tell you it can't generate reports.
 
+**Seeded admin.** By default the first person to register becomes the admin. Set `LAMBDA_ERP_ADMIN_EMAIL` + `LAMBDA_ERP_ADMIN_PASSWORD` to instead provision that admin automatically at startup — useful when the database is recreated on every deploy, so a redeployed instance can't be claimed by whoever visits first. It's create-if-missing and idempotent (an existing account with that email is promoted to an enabled admin; its password is left untouched), and the password is only ever read from the environment.
+
 ### Run the validation suite
 
 ```bash
@@ -326,12 +332,13 @@ for side-effects/integrations).
 
 ```python
 # acme/plugin.py
-from api.services import register_doctype, register_converter
+from api.services import register_doctype, register_master, register_converter
 from lambda_erp.hooks import register_hook
 from .sales_invoice import AcmeSalesInvoice
 
 def register():
     register_doctype("Sales Invoice", AcmeSalesInvoice)
+    register_master("gadget", "Gadget", "gadget_name", name_prefix="GAD")
     register_hook("Sales Invoice:after_submit", push_to_external_system)
     # register_converter(source, target, fn)   # only to replace conversion *logic*
 ```
@@ -340,6 +347,14 @@ Point the deployment at it with `LAMBDA_ERP_PLUGINS=acme` (comma-separated for
 several). On startup the core imports each module and calls `register()`. Unset
 = the core runs unchanged.
 
+A `register_master` type (core 0.5.0+) is served at `/api/masters/{slug}` and
+**discovered by the AI chat automatically**: `search_masters` (with fuzzy
+fallback), `get_master_fields`, and `create/update/delete_master` accept it
+from day one. The chat tool schemas and system prompt are built per request
+from the live registries, and fields are introspected from the live table — no
+per-type declarations. Details and caveats:
+[`docs/core-extension-architecture.md`](docs/core-extension-architecture.md).
+
 **Frontend overrides — the `@lambda-development/erp-core` library**
 
 The frontend ships as a library. The customer app depends on it, registers its

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/api/auth.py

@@ -630,6 +630,65 @@ def _setting_enabled(db, key: str) -> bool:
     return str(value) == "1"
 
 
+def ensure_seed_admin() -> dict | None:
+    """Idempotently provision an admin account from the environment.
+
+    When both LAMBDA_ERP_ADMIN_EMAIL and LAMBDA_ERP_ADMIN_PASSWORD are set,
+    guarantee an enabled admin with that email exists *before* the first
+    visitor can register. This closes the "first user to sign up becomes
+    admin" bootstrap window (see `register`) on any deployment whose
+    database is recreated on every rollout — e.g. the ephemeral-SQLite demo
+    container, where otherwise whichever stranger loads the login page first
+    after a redeploy would silently own the instance.
+
+    Create-if-missing: an existing account with that email is promoted to an
+    enabled admin if needed, but its password is left untouched so a redeploy
+    never clobbers a credential changed inside a live instance. The password
+    is read only from the environment and is never logged.
+
+    No-op (returns None) when either variable is unset — this is a general
+    ops seam, not demo-only.
+    """
+    email = os.environ.get("LAMBDA_ERP_ADMIN_EMAIL")
+    password = os.environ.get("LAMBDA_ERP_ADMIN_PASSWORD")
+    if not email or not password:
+        return None
+
+    email = email.strip().lower()
+    db = get_db()
+
+    existing = db.sql('SELECT name, role, enabled FROM "User" WHERE email = ?', [email])
+    if existing:
+        row = existing[0]
+        updates = {}
+        if row["role"] != "admin":
+            updates["role"] = "admin"
+        if not row["enabled"]:
+            updates["enabled"] = 1
+        if updates:
+            updates["modified"] = now()
+            db.set_value("User", row["name"], updates)
+            print(f"[seed-admin] promoted existing user to enabled admin: {email}", flush=True)
+        else:
+            print(f"[seed-admin] admin already present: {email}", flush=True)
+        return {"name": row["name"], "status": "exists"}
+
+    user_name = f"USR-{uuid.uuid4().hex[:8]}"
+    full_name = os.environ.get("LAMBDA_ERP_ADMIN_NAME", "Administrator")
+    db.insert("User", {
+        "name": user_name,
+        "email": email,
+        "full_name": full_name,
+        "hashed_password": hash_password(password),
+        "role": "admin",
+        "enabled": 1,
+        "creation": now(),
+        "modified": now(),
+    })
+    print(f"[seed-admin] created admin account: {email}", flush=True)
+    return {"name": user_name, "status": "created"}
+
+
 @router.get("/settings")
 def get_settings(user: dict = Depends(get_current_user)):
     db = get_db()

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/api/bootstrap.py

@@ -58,6 +58,16 @@ SETTING_DEMO_REDSTONE_SINV_DATE = "demo_chat_redstone_sinv_date"
 SETTING_DEMO_REDSTONE_DUE_DATE = "demo_chat_redstone_due_date"
 
 
+def _seed_setting_on(db, key: str) -> None:
+    """Turn a boolean Settings flag on, but only if it has never been set —
+    so an admin who later toggles it off in a persistent instance isn't
+    overridden on the next boot. On the ephemeral demo DB the key is always
+    absent at boot, so this reliably enables it there."""
+    if not db.sql('SELECT 1 FROM "Settings" WHERE key = ?', [key]):
+        db.sql('INSERT INTO "Settings" (key, value) VALUES (?, ?)', [key, "1"])
+        db.conn.commit()
+
+
 def bootstrap_demo() -> None:
     """Idempotent demo bootstrap. Logs each phase to stdout so a
     `docker compose up` user sees steady progress during the ~3-minute
@@ -131,7 +141,12 @@ def bootstrap_demo() -> None:
         create_public_manager(user=None)
         ensure_demo_chat_records(company)
     else:
-        print("[bootstrap] public demo disabled — first visitor registers as admin via the login page", flush=True)
+        # No public-manager replay: let visitors self-register as viewers so
+        # the demo is still hands-on. Admin is provisioned separately from the
+        # environment (see api.auth.ensure_seed_admin), so open signup here only
+        # ever mints viewers — nobody can grab admin off the login page.
+        _seed_setting_on(db, "allow_public_signup")
+        print("[bootstrap] public demo disabled — open viewer signup enabled; admin comes from LAMBDA_ERP_ADMIN_* env", flush=True)
 
     elapsed = time.monotonic() - t0
     # Recommend 127.0.0.1 — on WSL2 + Docker Desktop, browsers can stall

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/api/chat.py

@@ -463,7 +463,9 @@ TOOLS = [
                 "type": "object",
                 "properties": {
                     "doctype": {"type": "string", "enum": DOCUMENT_SLUGS, "description": "Document type slug"},
-                    "filters": {"type": "object", "description": "Optional filters like {\"status\": \"Draft\", \"customer\": \"CUST-001\"}", "default": {}},
+                    "filters": {"type": "object", "description": "Optional equality filters on any column, e.g. {\"status\": \"Draft\", \"customer\": \"CUST-001\", \"lead_id\": \"LEAD-3316\"}", "default": {}},
+                    "order_by": {"type": "string", "description": "Optional column to sort by (e.g. \"occurred_at\" for a timeline). Defaults to creation."},
+                    "order": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction (default desc)", "default": "desc"},
                     "limit": {"type": "integer", "description": "Max results (default 20, max 500)", "default": 20},
                 },
                 "required": ["doctype"],
@@ -1175,6 +1177,38 @@ def _extra_master_types():
     return sorted(m for m in services.MASTER_TABLES if m not in MASTER_TYPES)
 
 
+def _chat_doctype_section() -> str:
+    """A '## Custom record types' block for doctypes registered via
+    register_chat_doctype: each type's description, key fields, and its
+    LINK_FIELDS relationships (read live from the Document class). Tells the
+    model these are driven with the DOCUMENT tools and how they attach to a
+    parent (e.g. a contact links to a lead via `lead_id`). Empty when none."""
+    slugs = [s for s in services.CHAT_DOCTYPES if s in services.SLUG_TO_DOCTYPE]
+    if not slugs:
+        return ""
+    lines = []
+    for slug in slugs:
+        meta = services.CHAT_DOCTYPES[slug]
+        doctype = services.SLUG_TO_DOCTYPE[slug]
+        cls = services.DOCUMENT_CLASSES.get(doctype)
+        links = getattr(cls, "LINK_FIELDS", None) or {}
+        line = f"- **{doctype}** (slug `{slug}`): {meta['description']}"
+        if meta.get("fields"):
+            line += f" Key fields: {', '.join('`' + f + '`' for f in meta['fields'])}."
+        if links:
+            link_str = ", ".join(f"`{f}` → the {t}'s name" for f, t in links.items())
+            line += f" Links: {link_str}."
+        lines.append(line)
+    return (
+        "\n\n## Custom record types (deployment-specific)\n"
+        "Manage these with the DOCUMENT tools (`create_document`, `update_document`, "
+        "`list_documents`, `get_document`) — NOT the master tools — so their `validate()` "
+        "runs. To attach one to a parent, set its link field to the parent record's `name` "
+        "(find the parent first, e.g. with `search_masters` or `list_documents`). Do not put "
+        "child data on the parent's own fields.\n" + "\n".join(lines)
+    )
+
+
 def build_tools():
     """TOOLS with the doctype/master enums widened from the live registries.
 
@@ -1217,6 +1251,8 @@ def _handle_list_documents(args):
         args["doctype"],
         filters=args.get("filters"),
         limit=args.get("limit", 20),
+        order_by=args.get("order_by"),
+        order=args.get("order", "desc"),
     )
     for row in rows:
         for key in child_keys:
@@ -1898,6 +1934,7 @@ def build_system_prompt(user_info: dict | None = None, channel: str = "web"):
         f"display = `{services.MASTER_TABLES[m][1]}`"
         for m in extra_masters
     )
+    chat_doctype_section = _chat_doctype_section()
 
     # Channel-aware link guidance. On the "web" channel the reader is a browser
     # inside the ERP, so web-relative links are clickable. On the "api" channel the
@@ -2006,7 +2043,7 @@ When a user asks you to do something they don't have permission for, explain wha
 - **Buying:** purchase-order, purchase-invoice
 - **Accounting:** payment-entry, journal-entry, budget, subscription, bank-transaction
 - **Stock:** stock-entry, delivery-note, purchase-receipt
-- **Settings:** pricing-rule{extension_doctypes_line}
+- **Settings:** pricing-rule{extension_doctypes_line}{chat_doctype_section}
 
 ## Document Workflow & What Each Document Does
 

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/api/main.py

@@ -55,10 +55,22 @@ async def lifespan(app: FastAPI):
     # Load customer extension plugins before anything creates documents.
     load_plugins()
 
+    # Create plugin-registered tables and run their pending migrations. Must be
+    # after load_plugins() (registrations happen in register()) and before any
+    # document is created.
+    from api.services import apply_plugin_schema
+    apply_plugin_schema()
+
     # Ensure the demo spend log table exists before any LLM call happens.
     from api.demo_limits import init_schema as init_demo_spend_schema
     init_demo_spend_schema()
 
+    # Seed a deterministic admin from the environment (if configured) before
+    # anyone can register. On deployments whose DB is recreated each rollout
+    # this stops the first visitor after a redeploy from grabbing admin.
+    from api.auth import ensure_seed_admin
+    ensure_seed_admin()
+
     # When packaged as a demo container, land visitors straight in demo mode.
     if os.environ.get("LAMBDA_ERP_AUTO_DEMO") == "1":
         from api.bootstrap import bootstrap_demo

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/api/routers/documents.py

@@ -1,6 +1,6 @@
 """Generic CRUD routes for all document types."""
 
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import Response
 from api.services import (
     create_document,
@@ -12,6 +12,7 @@ from api.services import (
     convert_document,
     list_documents,
     count_documents,
+    document_columns,
 )
 from api.pdf import generate_pdf
 from api.auth import require_role
@@ -21,16 +22,26 @@ router = APIRouter(prefix="/documents", tags=["documents"])
 _viewer = Depends(require_role("viewer"))
 _manager = Depends(require_role("manager"))
 
+# Query params the list endpoint interprets itself — everything else is treated
+# as an ad-hoc column=value filter (validated against the doctype's columns).
+_LIST_RESERVED = {
+    "status", "party", "from_date", "to_date", "docstatus",
+    "include_discarded", "limit", "offset", "order_by", "order",
+}
+
 
 @router.get("/{doctype_slug}")
 def list_docs(
     doctype_slug: str,
+    request: Request,
     status: str | None = None,
     party: str | None = None,
     from_date: str | None = None,
     to_date: str | None = None,
     docstatus: int | None = None,
     include_discarded: bool = False,
+    order_by: str | None = None,
+    order: str = "desc",
     limit: int = Query(default=50, le=500),
     offset: int = Query(default=0, ge=0),
     _user: dict = _viewer,
@@ -46,8 +57,25 @@ def list_docs(
         filters["from_date"] = from_date
     if to_date:
         filters["to_date"] = to_date
+
+    # Ad-hoc equality filters: any remaining query param that names a real column
+    # of this doctype (e.g. /documents/activity?lead_id=LEAD-3316). Validate
+    # against the live columns so an unknown field is a 400, never interpolated.
+    columns = document_columns(doctype_slug)
+    for key, value in request.query_params.items():
+        if key in _LIST_RESERVED:
+            continue
+        if key not in columns:
+            raise HTTPException(status_code=400, detail=f"Unknown filter field: {key}")
+        filters[key] = value
+
+    if order_by is not None and order_by not in columns:
+        raise HTTPException(status_code=400, detail=f"Unknown order_by field: {order_by}")
+    if order.lower() not in ("asc", "desc"):
+        raise HTTPException(status_code=400, detail="order must be 'asc' or 'desc'")
+
     rows = list_documents(doctype_slug, filters=filters, limit=limit, offset=offset,
-                          include_discarded=include_discarded)
+                          include_discarded=include_discarded, order_by=order_by, order=order)
     total = count_documents(doctype_slug, filters=filters, include_discarded=include_discarded)
     return {"rows": rows, "total": total, "limit": limit, "offset": offset}
 

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/api/services.py

@@ -1,6 +1,6 @@
 """Bridge between FastAPI request data and lambda_erp Document classes."""
 
-from lambda_erp.utils import _dict
+from lambda_erp.utils import _dict, now
 from lambda_erp.database import get_db
 
 from lambda_erp.selling.quotation import (
@@ -114,6 +114,82 @@ def register_doctype(doctype: str, cls, slug: str | None = None) -> None:
     DOCTYPE_TO_SLUG[doctype] = slug
 
 
+# --- Plugin schema seam ---
+#
+# Core tables are created by database.setup(); plugin tables have no home there
+# (setup() runs before plugins load). These two registries let a plugin declare
+# its own tables and one-time migrations from register(); the core applies them
+# via apply_plugin_schema() in the app lifespan, right after load_plugins() and
+# before any document is created. See docs/core-extension-architecture.md.
+
+_PLUGIN_TABLES: list[str] = []
+_PLUGIN_MIGRATIONS: list = []  # list[tuple[str, Callable[[DB], None]]]
+
+
+def register_table(ddl: str) -> None:
+    """Register a CREATE TABLE (use IF NOT EXISTS) for a plugin table. The DDL is
+    the SQLite-flavoured subset the core's own DDL uses; apply_plugin_schema()
+    translates it per backend via db._ddl(). Idempotent — safe on every boot."""
+    _PLUGIN_TABLES.append(ddl)
+
+
+def register_migration(migration_id: str, fn) -> None:
+    """Register a one-shot migration run exactly once per database, recorded in
+    _PluginMigrations by `migration_id` (namespace it, e.g. "internal:0001_x").
+    `fn(db)` receives the DB; use db.ensure_column(...) for idempotent ALTERs
+    and plain db.sql(...) for backfills. Runs after registered tables exist, in
+    registration order. Must be idempotent and self-contained (single logical
+    unit — it commits on success)."""
+    _PLUGIN_MIGRATIONS.append((migration_id, fn))
+
+
+def apply_plugin_schema() -> None:
+    """Create registered plugin tables, then run pending plugin migrations once
+    each. Call from the app lifespan after load_plugins(). Table creation always
+    runs (IF NOT EXISTS); each migration runs only if its id isn't already in
+    _PluginMigrations. A failing migration is rolled back and left unrecorded so
+    it retries next boot; it does not abort startup (mirrors the core migrator)."""
+    db = get_db()
+    for ddl in _PLUGIN_TABLES:
+        db.conn.execute(db._ddl(ddl))
+    db.conn.commit()
+
+    if not _PLUGIN_MIGRATIONS:
+        return
+
+    db.conn.execute(
+        'CREATE TABLE IF NOT EXISTS "_PluginMigrations" '
+        "(migration_id TEXT PRIMARY KEY, applied_at TEXT NOT NULL)"
+    )
+    db.conn.commit()
+    applied = {r["migration_id"] for r in db.sql('SELECT migration_id FROM "_PluginMigrations"')}
+
+    for migration_id, fn in _PLUGIN_MIGRATIONS:
+        if migration_id in applied:
+            continue
+        try:
+            fn(db)
+            db.sql(
+                'INSERT INTO "_PluginMigrations" (migration_id, applied_at) VALUES (?, ?)',
+                [migration_id, now()],
+            )
+            db.conn.commit()
+            print(f"[plugin-migration] applied {migration_id}", flush=True)
+        except Exception as e:
+            db.conn.rollback()
+            print(f"[plugin-migration] FAILED {migration_id}: {e!r} — will retry next boot", flush=True)
+
+
+def document_columns(doctype_slug: str) -> set:
+    """The real column names of a registered doctype's table, or empty set if the
+    slug is unknown. Used to validate ad-hoc list filters against actual columns
+    (see the documents router) so an unknown field is a 400, never SQL."""
+    doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
+    if not doctype:
+        return set()
+    return get_db()._get_table_columns(doctype)
+
+
 def register_master(slug: str, table: str, name_field: str, *,
                     name_prefix: str | None = None,
                     identity_alias: str | None = None) -> None:
@@ -140,6 +216,23 @@ def register_master(slug: str, table: str, name_field: str, *,
         MASTER_IDENTITY_ALIAS[slug] = identity_alias
 
 
+# Chat guidance for registered doctypes: slug -> {"description", "fields"}. The
+# document tools (create/update/list/get_document) already accept any registered
+# doctype and run its validate(); this registry only teaches the AI chat WHAT a
+# custom doctype is and HOW it links, so it uses the validated document path
+# instead of, say, scribbling on a parent's fields. Relationships are read
+# automatically from the Document class's LINK_FIELDS — not declared here.
+CHAT_DOCTYPES: dict = {}
+
+
+def register_chat_doctype(slug: str, *, description: str, fields: list | None = None) -> None:
+    """Give the AI chat a description (and optional key-field hints) for a doctype
+    already registered via `register_doctype`, so build_system_prompt can tell the
+    model what it is and how it links (LINK_FIELDS are surfaced automatically).
+    No new tools — the document tools already cover every registered doctype."""
+    CHAT_DOCTYPES[slug] = {"description": description, "fields": fields or []}
+
+
 def get_document_class(doctype_slug: str):
     """Get document class from URL slug."""
     doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
@@ -272,8 +365,18 @@ def _exclude_discarded(db, doctype: str, db_filters: dict, include_discarded: bo
         db_filters["discarded"] = 0
 
 
+def _order_clause(order_by: str = None, order: str = "desc") -> str:
+    """ORDER BY clause for list queries. Defaults to newest-created first.
+    `order_by`, when given, must already be a validated column name (the
+    documents router checks it against document_columns) — it is quoted here."""
+    if not order_by:
+        return "creation DESC"
+    direction = "ASC" if str(order).lower() == "asc" else "DESC"
+    return f'"{order_by}" {direction}'
+
+
 def list_documents(doctype_slug: str, filters: dict = None, limit: int = 50, offset: int = 0,
-                   include_discarded: bool = False) -> list:
+                   include_discarded: bool = False, order_by: str = None, order: str = "desc") -> list:
     doctype = SLUG_TO_DOCTYPE.get(doctype_slug)
     if not doctype:
         raise ValueError(f"Unknown document type: {doctype_slug}")
@@ -315,15 +418,17 @@ def list_documents(doctype_slug: str, filters: dict = None, limit: int = 50, off
             db, doctype, doctype_slug, db_filters, date_field, from_date, to_date, limit, offset
         )
 
+    order_clause = _order_clause(order_by, order)
+
     # get_all doesn't support offset, so use raw SQL when needed
     if offset:
-        return _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset)
+        return _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset, order_clause)
 
     rows = db.get_all(
         doctype,
         filters=db_filters if db_filters else None,
         fields=["*"],
-        order_by="creation DESC",
+        order_by=order_clause,
         limit=limit,
     )
 
@@ -378,7 +483,7 @@ def count_documents(doctype_slug: str, filters: dict = None, include_discarded:
     return int(rows[0]["c"]) if rows else 0
 
 
-def _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset):
+def _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset, order_clause="creation DESC"):
     where_parts = []
     params = []
     for k, v in db_filters.items():
@@ -392,7 +497,7 @@ def _list_with_offset(db, doctype, doctype_slug, db_filters, limit, offset):
     query = f'SELECT * FROM "{doctype}"'
     if where_parts:
         query += " WHERE " + " AND ".join(where_parts)
-    query += " ORDER BY creation DESC"
+    query += f" ORDER BY {order_clause}"
     if limit:
         query += f" LIMIT {int(limit)}"
     if offset:

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/lambda_erp/database.py

@@ -1391,6 +1391,14 @@ class Database:
             self._col_cache.pop(table, None)
             self._text_col_cache.pop(table, None)
 
+    def ensure_column(self, table: str, column: str, definition: str) -> None:
+        """Idempotently add a column if it's missing. Public helper for plugin
+        migrations registered via api.services.register_migration — the same
+        backend-portable, PRAGMA/information_schema-guarded add the core's own
+        migrations use. `definition` is the SQLite-flavoured column type (e.g.
+        "TEXT", "INTEGER DEFAULT 0"); it is translated per dialect via _ddl."""
+        self._add_column_if_missing(table, column, definition)
+
     def _migrate(self):
         """Run each pending migration in order, tracking applied versions."""
         self.conn.execute(

{lambda_erp-0.5.0 → lambda_erp-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lambda-erp"
-version = "0.5.0"
+version = "0.6.1"
 description = "Core ERP logic - accounting, sales, purchasing, inventory"
 readme = "README.md"
 license = "Apache-2.0"