lambda-erp 0.8.20__tar.gz → 0.8.22__tar.gz

{lambda_erp-0.8.20 → lambda_erp-0.8.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lambda-erp
-Version: 0.8.20
+Version: 0.8.22
 Summary: Core ERP logic - accounting, sales, purchasing, inventory
 Author: TORUS INVESTMENTS AG
 License-Expression: Apache-2.0
@@ -8,6 +8,7 @@ License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: anthropic>=0.40
 Requires-Dist: bcrypt>=5
+Requires-Dist: defusedxml>=0.7
 Requires-Dist: fastapi>=0.115
 Requires-Dist: holidays>=0.40
 Requires-Dist: httpx>=0.27
@@ -92,7 +93,7 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
                                                ▼
                            ┌──────────────────────────────────────────┐
                            │  LLM orchestrator                        │
-                           │  - GPT-5.4 drives the reasoning loop     │
+                           │  - GPT-5.6 drives the reasoning loop     │
                            │  - Tool-use: document CRUD, search,      │
                            │    reports, aggregations, analytics      │
                            │  - Delegates JS generation to Anthropic  │
@@ -449,9 +450,9 @@ replacement file.
 Both the backend seams (document classes, lifecycle hooks, converters, plugin
 loading) and the frontend seams (doctype/route/nav/component registries,
 branding, configurable API base, Tailwind preset) are implemented. The backend
-also builds a clean pip wheel and the frontend a `@lambda-development/erp-core` npm library
-— see [`docs/packaging-distribution-plan.md`](docs/packaging-distribution-plan.md)
-for the publish path.
+ships as a pip package and the frontend as the
+`@lambda-development/erp-core` npm package. See
+[`docs/releasing.md`](docs/releasing.md) for the release process.
 
 ---
 

{lambda_erp-0.8.20 → lambda_erp-0.8.22}/README.md

@@ -64,7 +64,7 @@ Each of those is hours of skilled work today. With a capable LLM in the loop, th
                                                ▼
                            ┌──────────────────────────────────────────┐
                            │  LLM orchestrator                        │
-                           │  - GPT-5.4 drives the reasoning loop     │
+                           │  - GPT-5.6 drives the reasoning loop     │
                            │  - Tool-use: document CRUD, search,      │
                            │    reports, aggregations, analytics      │
                            │  - Delegates JS generation to Anthropic  │
@@ -421,9 +421,9 @@ replacement file.
 Both the backend seams (document classes, lifecycle hooks, converters, plugin
 loading) and the frontend seams (doctype/route/nav/component registries,
 branding, configurable API base, Tailwind preset) are implemented. The backend
-also builds a clean pip wheel and the frontend a `@lambda-development/erp-core` npm library
-— see [`docs/packaging-distribution-plan.md`](docs/packaging-distribution-plan.md)
-for the publish path.
+ships as a pip package and the frontend as the
+`@lambda-development/erp-core` npm package. See
+[`docs/releasing.md`](docs/releasing.md) for the release process.
 
 ---
 

{lambda_erp-0.8.20 → lambda_erp-0.8.22}/api/attachments.py

@@ -49,10 +49,17 @@ OFFICE_MIME_TYPES = {
 # Plain-text formats — inlined into the prompt as text (no file part needed).
 TEXT_MIME_TYPES = {"text/csv", "text/plain"}
 
+# Structured bank uploads are retained as ordinary chat attachments, but are
+# never dumped wholesale into the LLM context. Dedicated deterministic tools
+# parse them and return a compact preview instead.
+STRUCTURED_TOOL_MIME_TYPES = {
+    "application/xml", "text/xml", "application/zip", "application/x-zip-compressed",
+}
+
 ALLOWED_MIME_TYPES = {
     "image/png", "image/jpeg", "image/gif", "image/webp",
     "application/pdf",
-} | OFFICE_MIME_TYPES | TEXT_MIME_TYPES
+} | OFFICE_MIME_TYPES | TEXT_MIME_TYPES | STRUCTURED_TOOL_MIME_TYPES
 
 # Extension -> canonical mime, so a correctly-named file still uploads when the
 # browser/OS mislabels its type (Office files are frequently sent as
@@ -69,6 +76,8 @@ _EXT_TO_MIME = {
     "odp": "application/vnd.oasis.opendocument.presentation",
     "csv": "text/csv",
     "txt": "text/plain",
+    "xml": "application/xml",
+    "zip": "application/zip",
     "pdf": "application/pdf",
     "png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg",
     "gif": "image/gif", "webp": "image/webp",
@@ -240,7 +249,8 @@ async def upload_attachment(
             raise HTTPException(
                 status_code=400,
                 detail=(f"Unsupported file type: {mime or ext or 'unknown'}. Allowed: images, PDF, "
-                        "spreadsheets (Excel/CSV/ODS), and documents (Word/OpenDocument)."),
+                        "spreadsheets (Excel/CSV/ODS), documents (Word/OpenDocument), "
+                        "and structured bank files (XML/ZIP)."),
             )
 
     data = await file.read()
@@ -389,6 +399,14 @@ def build_multimodal_content(attachment: dict) -> dict:
             "type": "image_url",
             "image_url": {"url": f"data:{mime};base64,{data_b64}"},
         }
+    if mime in STRUCTURED_TOOL_MIME_TYPES:
+        return {
+            "type": "text",
+            "text": (
+                f"[Structured attachment: {filename}. Do not retrieve or parse its raw contents in "
+                "the conversation; use the dedicated bank-statement preview tool.]"
+            ),
+        }
     if mime in TEXT_MIME_TYPES or mime.startswith("text/"):
         text = attachment["data"].decode("utf-8", errors="replace")
         return {"type": "text", "text": f"[File: {filename}]\n{text}"}

{lambda_erp-0.8.20 → lambda_erp-0.8.22}/api/auth.py

@@ -612,7 +612,7 @@ DEFAULTS = {
     "allow_public_signup": "0",
     # When "1", the programmatic chat API (POST /api/v1/chat, Bearer API keys) is
     # active. Default off — an admin turns it on and issues keys. See
-    # docs/chat-api-plan.md.
+    # docs/chat-api.md.
     "chat_api_enabled": "0",
     # When "1", the same Bearer API keys authenticate the regular REST API
     # (/api/documents, /api/masters, /api/reports, …) in addition to the session

{lambda_erp-0.8.20 → lambda_erp-0.8.22}/api/chat.py

@@ -448,7 +448,7 @@ DOCUMENT_SLUGS = [
     "purchase-order", "purchase-invoice",
     "payment-entry", "journal-entry", "stock-entry",
     "delivery-note", "purchase-receipt", "pos-invoice",
-    "pricing-rule", "budget", "subscription", "bank-transaction",
+    "pricing-rule", "budget", "subscription", "bank-account", "bank-transaction",
     # Owned equipment and its hire calendar. Core doctypes, so they belong in
     # this list rather than surfacing as "deployment-specific extensions"
     # (_extra_document_slugs is defined as everything NOT named here).
@@ -478,6 +478,20 @@ TOOLS = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_document_fields",
+            "description": "List the available columns of a document type and identify which are text fields. Call this before building list_documents filters when you are unsure of a field name or whether it supports the case-insensitive contains operator. Also returns the default fields used by free-text search.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "doctype": {"type": "string", "enum": DOCUMENT_SLUGS},
+                },
+                "required": ["doctype"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -627,7 +641,7 @@ TOOLS = [
         "type": "function",
         "function": {
             "name": "search_masters",
-            "description": "Search master data (customers, suppliers, items, warehouses, accounts, companies, cost centers). Case-insensitive, with fuzzy fallback for misspellings. By default matches across standard text fields (name, display name, address/city/zip); large free-text columns like description/templates are skipped unless named in `fields`. PREFER passing `fields` whenever you know which attribute you're matching on (e.g. a city, an email, a tax id) — it's faster, more precise, and avoids false hits from other columns. Returns ALL matching records by default (no cap); pass `limit` only to bound a large list.",
+            "description": "Search and filter master data (customers, suppliers, items, warehouses, accounts, companies, cost centers). `query` is a case-insensitive free-text lookup with fuzzy fallback for simple misspellings. Use `filters` for deterministic field-aware queries and for combining different values across fields. Returns ALL matching records by default (no cap); pass `limit` only to bound a large list.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -638,7 +652,20 @@ TOOLS = [
                         "items": {"type": "string"},
                         "description": "Recommended: the column(s) to search, e.g. [\"city\"] or [\"customer_name\"]. Narrowing here is faster and avoids matching unrelated columns. Omit only when you genuinely don't know which field holds the value, to search all standard text fields.",
                     },
+                    "filters": {
+                        "type": "object",
+                        "description": "Optional deterministic filters on any real column, ANDed together and with `query`. Scalar values are exact: {\"disabled\": 0}. Text substring: {\"legal_form\": [\"contains\", \"AG\"]}. Comparisons and NULL checks use the same forms as list_documents. `contains` is only valid for schema-confirmed text fields.",
+                        "default": {},
+                    },
+                    "order_by": {"type": "string", "description": "Optional real column to sort by. Defaults to name."},
+                    "order": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction (default asc).", "default": "asc"},
                     "limit": {"type": "integer", "description": "Optional max number of results. OMIT for no cap — returns ALL matches (e.g. to see the entire chart of accounts). Pass a number only to bound a large list."},
+                    "offset": {"type": "integer", "description": "Skip this many matching rows. Use with limit for pagination.", "default": 0},
+                    "result_fields": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional result projection. Returns only these real columns plus name. This is separate from `fields`, which selects columns searched by `query`.",
+                    },
                     "include_disabled": {"type": "boolean", "description": "Default false (active records only). Set true to ALSO return disabled/archived records — needed to find a record you must inspect, re-enable, or reference, or to answer 'what's disabled'. Retry with this if a lookup for a record you know exists comes back empty."},
                 },
                 "required": ["master_type"],
@@ -649,7 +676,7 @@ TOOLS = [
         "type": "function",
         "function": {
             "name": "get_master_fields",
-            "description": "List the available columns of a master type (customer, supplier, item, ...). Call this WHENEVER you're unsure which columns exist: before passing `fields` to search_masters, and before building a `data` payload for create_master/update_master when you're not certain a field exists or where a value belongs (e.g. a contact person, a tax id, a payment term). It lets you target real fields instead of guessing — or wrongly concluding a value can't be stored. Returns: `fields` (all columns), `default_search_fields` (what search_masters searches when `fields` is omitted), and `bulk_text_fields` (large text columns searched only when named in `fields`).",
+            "description": "List the available columns of a master type (customer, supplier, item, ...). Call this WHENEVER you're unsure which columns exist: before passing `fields` or `filters` to search_masters, and before building a create/update payload. Returns all fields, text fields (the columns that support `contains`), default free-text search fields, and bulk text fields that are searched only when explicitly named.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -787,10 +814,58 @@ TOOLS = [
         "type": "function",
         "function": {
             "name": "list_chat_attachments",
-            "description": "List all files the user has uploaded in this chat session — PDFs, images, spreadsheets (Excel/CSV/ODS), and documents (Word/OpenDocument). Returns metadata including id, filename, mime type, size, and upload date. Use this when the user references a previously uploaded file or you need to find an attachment to retrieve.",
+            "description": "List all files the user has uploaded in this chat session — PDFs, images, spreadsheets (Excel/CSV/ODS), documents (Word/OpenDocument), and structured bank files (CAMT XML/ZIP). Returns metadata including id, filename, mime type, size, and upload date. Use this when the user references a previously uploaded file or you need its attachment id.",
             "parameters": {"type": "object", "properties": {}},
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "preview_bank_statement_attachments",
+            "description": "Safely parse CAMT.053 XML or ZIP chat attachments and return a compact, read-only import preview: masked account, currency, period, balances, entry/detail/batch/QR counts, duplicates, warnings, and any exact Bank Account mapping. The raw XML is never added to the model context. Always call this before importing bank statements.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "attachment_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "minItems": 1,
+                        "maxItems": 20,
+                        "description": "CAMT XML/ZIP attachment ids from this chat.",
+                    },
+                },
+                "required": ["attachment_ids"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "import_bank_statement_attachments",
+            "description": "Import previously previewed CAMT attachments as Bank Transactions without creating or posting any Payment Entry, Journal Entry, or GL entry. Exact file re-uploads and stable duplicate bank entries are skipped. Use only after showing the preview and receiving explicit user confirmation. Requires manager access and is unavailable in public demo mode.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "attachment_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "minItems": 1,
+                        "maxItems": 20,
+                    },
+                    "mappings": {
+                        "type": "object",
+                        "additionalProperties": {"type": "string"},
+                        "description": "Optional mapping of statement_key from the preview to Bank Account document name. Exact IBAN matches are used automatically.",
+                    },
+                    "confirmed": {
+                        "type": "boolean",
+                        "description": "Must be true, and only after the user explicitly confirmed the displayed preview.",
+                    },
+                },
+                "required": ["attachment_ids", "confirmed"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -1275,15 +1350,20 @@ def build_tools(user_info: dict | None = None):
     extra_docs = _extra_document_slugs()
     extra_masters = _extra_master_types()
     action_tools = services.registered_action_tools()
+    hidden_tools: set[str] = set()
     if user_info is not None:
         role = user_info.get("role")
         action_tools = [
             tool for tool in action_tools
             if services.registered_action_allowed(tool["function"]["name"], role)
         ]
-    if not extra_docs and not extra_masters and not action_tools:
+        if role not in {"manager", "admin"}:
+            hidden_tools.add("import_bank_statement_attachments")
+    if not extra_docs and not extra_masters and not action_tools and not hidden_tools:
         return TOOLS
     tools = copy.deepcopy(TOOLS)
+    if hidden_tools:
+        tools = [tool for tool in tools if tool["function"]["name"] not in hidden_tools]
     for tool in tools:
         props = tool["function"].get("parameters", {}).get("properties", {})
         for schema in props.values():
@@ -1326,18 +1406,6 @@ def _handle_list_documents(args):
     # within the tool-result budget. Use get_document to drill into one doc.
     doctype = args["doctype"]
     filters = args.get("filters") or {}
-    # Chat callers routinely pass `search` but omit `search_fields`; with no fields
-    # the free-text search silently no-ops and returns the newest N by creation
-    # (2026-08-13: tag lookups on leads "found nothing"). Default the columns to the
-    # doctype's registered chat fields so document search matches a record the way
-    # search_masters already does for masters. The frontend never hits this — its
-    # UI config always sends search_fields.
-    if filters.get("search") and not filters.get("search_fields"):
-        registered = (services.CHAT_DOCTYPES.get(doctype) or {}).get("fields") or []
-        valid = set(services.document_columns(doctype) or [])
-        default_fields = [f for f in registered if f in valid]
-        if default_fields:
-            filters = {**filters, "search_fields": default_fields}
     err = _validate_filter_columns(doctype, filters)
     if err:
         return {"error": err}
@@ -1369,6 +1437,23 @@ def _handle_list_documents(args):
     return rows
 
 
+def _handle_get_document_fields(args):
+    doctype = args["doctype"]
+    table = services.SLUG_TO_DOCTYPE.get(doctype)
+    if not table:
+        return {"error": f"Unknown document type: {doctype}"}
+    db = get_db()
+    cls = services.DOCUMENT_CLASSES.get(table)
+    return {
+        "doctype": doctype,
+        "fields": sorted(db._get_table_columns(table)),
+        "text_fields": sorted(db._get_text_columns(table)),
+        "default_search_fields": services.document_search_columns(db, doctype),
+        "child_tables": sorted((cls.CHILD_TABLES or {}).keys()) if cls else [],
+        "link_fields": dict(getattr(cls, "LINK_FIELDS", None) or {}) if cls else {},
+    }
+
+
 def _handle_get_document(args):
     return services.load_document(args["doctype"], args["name"])
 
@@ -1407,22 +1492,6 @@ def _handle_convert_document(args):
     return services.convert_document(args["doctype"], args["name"], args["target_doctype"])
 
 
-# Columns that are technically text but are noise for free-text master search.
-_MASTER_SEARCH_SKIP_COLUMNS = {
-    "naming_series",
-    "owner",
-    "modified_by",
-    "creation",
-    "modified",
-    "created_at",
-    "updated_at",
-}
-
-# Large free-text columns excluded from the DEFAULT search: scanning/fuzzing a
-# big blob (e.g. an item description or an HTML template) is costly and rarely
-# how you identify a record. Still searchable on demand via the `fields` arg.
-_MASTER_BULK_TEXT_COLUMNS = {"description", "notes", "remarks", "terms", "comments"}
-
 # Minimum difflib similarity for a fuzzy (misspelled) match to be returned.
 _MASTER_FUZZY_THRESHOLD = 0.6
 # Bounds for the fuzzy scorer so a single large value can't blow up cost:
@@ -1431,18 +1500,9 @@ _FUZZY_MAX_VALUE_LEN = 200
 _FUZZY_MAX_TOKENS = 16
 
 
-def _is_bulk_text_column(col):
-    return (col in _MASTER_BULK_TEXT_COLUMNS
-            or col.endswith("_template") or col.endswith("_html"))
-
-
 def _master_search_columns(db, doctype):
-    """Text columns worth matching a query against by default. Discovered from
-    the live schema (new text fields become searchable automatically), minus
-    audit noise and large free-text/template columns."""
-    cols = db._get_text_columns(doctype) - _MASTER_SEARCH_SKIP_COLUMNS
-    # Deterministic order keeps generated SQL and fuzzy scoring stable.
-    return sorted(c for c in cols if not _is_bulk_text_column(c))
+    """Compatibility wrapper for the shared REST/MCP field policy."""
+    return services.master_search_columns(db, doctype)
 
 
 def _fuzzy_master_search(db, doctype, search_cols, query, has_disabled, limit):
@@ -1485,10 +1545,11 @@ def _handle_get_master_fields(args):
         return {"error": f"Unknown master type: {master_type}"}
     doctype, _ = entry
     default_search = _master_search_columns(db, doctype)
-    bulk = sorted(c for c in db._get_text_columns(doctype) if _is_bulk_text_column(c))
+    bulk = services.master_bulk_text_columns(db, doctype)
     return {
         "master_type": master_type,
         "fields": sorted(db._get_table_columns(doctype)),
+        "text_fields": sorted(db._get_text_columns(doctype)),
         # What search_masters searches when `fields` is omitted.
         "default_search_fields": default_search,
         # Large text fields searched ONLY when named in search_masters `fields`.
@@ -1517,23 +1578,20 @@ def _handle_search_masters(args):
         return {"error": f"Unknown master type: {master_type}"}
 
     doctype, _name_field = entry
-    has_disabled = "disabled" in db._get_table_columns(doctype)
+    columns = set(db._get_table_columns(doctype))
+    has_disabled = "disabled" in columns
     # Active-only by default (retired/archived records are hidden — you shouldn't
     # book to them or wade through them). Set include_disabled to reach a disabled
     # record you need to inspect, re-enable, or reference. Only meaningful when the
     # table has a `disabled` column.
     filter_disabled = has_disabled and not bool(args.get("include_disabled"))
 
-    if not query:
-        filters = {"disabled": 0} if filter_disabled else None
-        return db.get_all(doctype, filters=filters, fields=["*"], limit=limit)
-
     # Optional `fields` narrows the search to specific columns — cheaper, more
     # precise, and the only way to reach bulk columns (description, templates)
     # that the default search skips. Unknown names are ignored.
     requested = args.get("fields") or []
     if requested:
-        valid = set(db._get_table_columns(doctype))
+        valid = columns
         # The identity alias (e.g. "item_code") is what the model calls the code
         # everywhere else — create_master, document lines, the asset/reservation
         # prompt — so it naturally passes fields=["item_code"]. But the real
@@ -1556,22 +1614,36 @@ def _handle_search_masters(args):
     else:
         search_cols = _master_search_columns(db, doctype)
 
-    active_prefix = "disabled = 0 AND " if filter_disabled else ""
-
-    # Case-insensitive substring match. lower() on both sides is portable (bare
-    # LIKE is case-insensitive on SQLite but case-sensitive on Postgres, which
-    # silently broke prod search); CAST lets targeted non-text columns match too.
-    where = " OR ".join(f'lower(CAST("{col}" AS TEXT)) LIKE ?' for col in search_cols)
-    pattern = f"%{query.lower()}%"
-    limit_sql = f" LIMIT {limit}" if limit else ""
-    rows = db.sql(
-        f'SELECT * FROM "{doctype}" WHERE {active_prefix}({where}){limit_sql}',
-        [pattern] * len(search_cols),
-    )
-    if rows:
-        return [dict(r) for r in rows]
-
-    # Nothing matched literally — try fuzzy matching to catch misspellings.
+    filters = args.get("filters") or {}
+    result_fields = args.get("result_fields") or None
+    offset = args.get("offset", 0) or 0
+    order_by = args.get("order_by")
+    order = args.get("order", "asc")
+    try:
+        result = services.list_master_records(
+            master_type,
+            filters=filters,
+            search=query or None,
+            search_fields=search_cols if query else None,
+            include_disabled=bool(args.get("include_disabled")),
+            order_by=order_by,
+            order=order,
+            limit=limit,
+            offset=offset,
+            fields=result_fields,
+            with_total=False,
+        )
+    except (TypeError, ValueError) as exc:
+        return {"error": str(exc)}
+    rows = [dict(row) for row in result["rows"]]
+    if rows or not query:
+        return rows
+
+    # Preserve the established fuzzy fallback for a simple lookup. A
+    # deterministic field-filter query must return exactly its literal result;
+    # relaxing only the free-text part could otherwise select the wrong record.
+    if filters or offset or order_by or result_fields:
+        return []
     return _fuzzy_master_search(db, doctype, search_cols, query, filter_disabled, limit=limit)
 
 
@@ -1794,6 +1866,98 @@ def _handle_retrieve_chat_attachment(args, session_id: str | None = None, user_i
     }
 
 
+def _load_camt_chat_attachments(args, user_id: str | None):
+    attachment_ids = args.get("attachment_ids") or []
+    if not user_id:
+        return None, {"error": "No authenticated user for bank statement attachments."}
+    if not isinstance(attachment_ids, list) or not 1 <= len(attachment_ids) <= 20:
+        return None, {"error": "attachment_ids must contain between 1 and 20 attachment ids."}
+    from api.attachments import get_attachments_by_ids
+    from lambda_erp.accounting.camt import CamtError, parse_camt_upload
+
+    attachments = get_attachments_by_ids(attachment_ids, user_id)
+    found = {item["id"] for item in attachments}
+    missing = [item for item in attachment_ids if item not in found]
+    if missing:
+        return None, {"error": "One or more attachments were not found or access was denied."}
+    documents = []
+    try:
+        for attachment in attachments:
+            documents.extend(parse_camt_upload(attachment["data"], attachment["filename"]))
+    except CamtError as exc:
+        return None, {"error": str(exc)}
+    return documents, None
+
+
+def _handle_preview_bank_statement_attachments(args, user_id: str | None = None):
+    documents, error = _load_camt_chat_attachments(args, user_id)
+    if error:
+        return error
+    from lambda_erp.accounting.bank_statement_import import preview_documents
+    return preview_documents(documents)
+
+
+def _handle_import_bank_statement_attachments(args, user_info: dict | None = None):
+    role = (user_info or {}).get("role")
+    if role not in {"manager", "admin"}:
+        return {"error": "Importing bank statements requires manager access and is unavailable in demo mode."}
+    if args.get("confirmed") is not True:
+        return {
+            "error": (
+                "Explicit confirmation is required. Show the bank statement preview, ask the user "
+                "to confirm it, and call the import tool in a later turn with confirmed=true."
+            )
+        }
+    user_id = (user_info or {}).get("name")
+    documents, error = _load_camt_chat_attachments(args, user_id)
+    if error:
+        return error
+    from lambda_erp.accounting.bank_statement_import import import_documents, preview_documents
+    from lambda_erp.exceptions import ValidationError
+
+    mappings = args.get("mappings") or {}
+    if not isinstance(mappings, dict):
+        return {"error": "mappings must be an object of statement_key to Bank Account name."}
+    # Exact IBAN matches are safe to fill automatically; anything ambiguous or
+    # unmapped is returned to the model as a focused question for the user.
+    preview = preview_documents(documents)
+    effective_mappings = dict(mappings)
+    missing = []
+    for statement in preview["statements"]:
+        if statement["already_imported"]:
+            continue
+        key = statement["statement_key"]
+        matched = statement.get("matched_bank_account")
+        if key not in effective_mappings and matched:
+            effective_mappings[key] = matched["name"]
+        if key not in effective_mappings:
+            missing.append({
+                "statement_key": key,
+                "file_name": statement["file_name"],
+                "account_iban_masked": statement["account_iban_masked"],
+                "currency": statement["account_currency"],
+            })
+    if missing:
+        return {
+            "error": "Bank Account mapping is required before import.",
+            "unmapped_statements": missing,
+        }
+    try:
+        result = import_documents(
+            documents, effective_mappings, imported_by=user_id
+        )
+    except ValidationError as exc:
+        return {"error": str(exc)}
+    # Keep the model context bounded even for multi-year statements.
+    return {
+        "imports": [
+            {key: value for key, value in item.items() if key != "transactions"}
+            for item in result["imports"]
+        ],
+        "exact_duplicate_imports": result["exact_duplicate_imports"],
+    }
+
+
 def _handle_query_dataset(args):
     from api.routers.analytics import aggregate_semantic_dataset
 
@@ -1932,6 +2096,7 @@ def _handle_apply_company_setup(args):
 
 TOOL_HANDLERS = {
     "list_documents": _handle_list_documents,
+    "get_document_fields": _handle_get_document_fields,
     "get_document": _handle_get_document,
     "create_document": _handle_create_document,
     "update_document": _handle_update_document,
@@ -1950,6 +2115,8 @@ TOOL_HANDLERS = {
     "retrieve_chat_history": lambda args: _handle_retrieve_chat_history(args),
     "list_chat_attachments": _handle_list_chat_attachments,
     "retrieve_chat_attachment": _handle_retrieve_chat_attachment,
+    "preview_bank_statement_attachments": _handle_preview_bank_statement_attachments,
+    "import_bank_statement_attachments": _handle_import_bank_statement_attachments,
     "query_dataset": _handle_query_dataset,
     "create_custom_analytics_report": lambda args: _handle_create_custom_analytics_report(args),
     "get_custom_analytics_report": lambda args: _handle_get_custom_analytics_report(args),
@@ -2183,13 +2350,31 @@ When a user asks you to do something they don't have permission for, explain wha
 ## Available Document Types (use the slug when calling tools)
 - **Selling:** quotation, proposal, sales-order, sales-invoice, pos-invoice
 - **Buying:** purchase-order, purchase-invoice
-- **Accounting:** payment-entry, journal-entry, budget, subscription, bank-transaction
+- **Accounting:** payment-entry, journal-entry, budget, subscription, bank-account, bank-transaction
 - **Stock:** stock-entry, delivery-note, purchase-receipt
 - **Assets & hire:** asset, reservation
 - **Settings:** pricing-rule{extension_doctypes_line}{chat_doctype_section}
 
 ## Document Workflow & What Each Document Does
 
+### CAMT bank statement imports
+CAMT XML/ZIP attachments are structured financial inputs. Never retrieve their raw contents into
+the conversation and never try to interpret the XML manually. Use this workflow:
+1. Find the attachment ids with `list_chat_attachments` when necessary.
+2. Call `preview_bank_statement_attachments` and present its period, masked account, currency,
+   opening/closing balances, credits/debits, entry/detail/batch counts, QR-reference count,
+   duplicate status, warnings, and proposed Bank Account mapping.
+3. If there is no exact mapping, list or create a `bank-account` document. It must link the external
+   IBAN to the correct Company and GL Account; never guess that accounting mapping.
+4. Ask the user for explicit confirmation after showing the preview. Do not call the import tool in
+   the same turn in which you first show the preview.
+5. Only after that confirmation, call `import_bank_statement_attachments` with `confirmed=true`.
+
+The CAMT import creates unposted Bank Transactions and their batch details only. It never creates,
+submits, or posts a Payment Entry, Journal Entry, or GL Entry. Do not imply that invoices have been
+settled or the ledger changed merely because a statement was imported. Matching/reconciliation is a
+separate later step. Keep Bank Account IBANs masked in ordinary chat responses.
+
 ### Sales Cycle
 Quotation → Sales Order → Delivery Note (shipping) / Sales Invoice (billing) → Payment Entry
 Shortcuts: Quotation can also convert directly to Sales Invoice or Delivery Note (skipping Sales Order) for quick deals.
@@ -2405,10 +2590,10 @@ Every master record has a primary key (the `name` column) and a human-readable d
 When you fill in `item_code`, `customer`, `supplier`, `warehouse`, `company`, etc. in a document or child-table row, you MUST use the **primary key**, never the display name. `"item_code": "Project Management"` is ALWAYS wrong — it's a name, not a code.
 
 If the user refers to something by its human name ("bill them 8 hours of project mgmt", "add Redstone to the quote"), resolve the key first:
-- `search_masters(master_type="item", q="project management")` → returns `[{{name: "SVC-005", item_name: "Project Management"}}]`. Use `name` as `item_code`.
+- `search_masters(master_type="item", query="project management")` → returns `[{{name: "SVC-005", item_name: "Project Management"}}]`. Use `name` as `item_code`.
 - Same for customers, suppliers, warehouses, etc. — `search_masters` is **case-insensitive** and falls back to **fuzzy matching for misspellings**, so a typo'd name ("Meynex") still resolves. Trust its results instead of concluding "not found" after one narrow try.
 - **Prefer narrowing with `fields`** whenever you know the attribute: search a customer by city with `fields=["city"]`, by email with `fields=["contact_email"]`, etc. It's faster and avoids false matches from unrelated columns. Omitting `fields` searches all standard text fields (a good fallback when you're unsure where the value lives), but large free-text columns (e.g. item `description`) are only searched when you name them explicitly in `fields`.
-- **Don't guess column names** — call `get_master_fields(master_type=...)` first to see the real columns (and which are searched by default), then pass the exact names to `search_masters` `fields`. This also tells you which large text fields (like `description`) you must name explicitly to search.
+- **Don't guess column names** — call `get_master_fields(master_type=...)` first to see the real columns, which support `contains`, and which are searched by default. Use `query` + `fields` for a fuzzy lookup; use `filters` for exact, combined field conditions. For documents, use `get_document_fields` before constructing unfamiliar `list_documents` filters.
 - **When unsure where a value belongs, discover the schema — don't guess or give up.** Before a `create_master`/`update_master` where you're not certain a field exists or which column fits (the user gives a contact person, a VAT/tax id, a payment term, an IBAN, …), call `get_master_fields(master_type=...)` and map the value onto the real column. Never tell the user you can't store something without checking the fields first — the master usually has a column for it (e.g. a customer's contact person goes in `contact_person`/`contact_phone`/`contact_email`, not the company-level `phone`/`email`).
 
 When you list masters back to the user (items on an invoice, customers on a report), include the key in parentheses so follow-ups are unambiguous. Example: "Project Management (SVC-005) — 16 Hour".
@@ -3022,6 +3207,12 @@ async def run_thinking_loop(
         tool_handlers["retrieve_chat_history"] = lambda args: _handle_retrieve_chat_history(args, session_id)
         user_id_for_tools = user_info.get("name") if user_info else None
         tool_handlers["list_chat_attachments"] = lambda args: _handle_list_chat_attachments(args, session_id, user_id_for_tools)
+        tool_handlers["preview_bank_statement_attachments"] = (
+            lambda args: _handle_preview_bank_statement_attachments(args, user_id_for_tools)
+        )
+        tool_handlers["import_bank_statement_attachments"] = (
+            lambda args: _handle_import_bank_statement_attachments(args, user_info)
+        )
         _scoped_retrieve_attachment = (
             lambda args: _handle_retrieve_chat_attachment(args, session_id, user_id_for_tools)
         )

{lambda_erp-0.8.20 → lambda_erp-0.8.22}/api/main.py

@@ -19,7 +19,7 @@ from api.auth import router as auth_router, COOKIE_NAME, decode_token
 from api.oauth import router as oauth_router
 from api.attachments import router as attachments_router
 from api.chat import chat_websocket, router as chat_router
-from api.routers import admin, documents, masters, reports, setup as setup_router, bank_reconciliation, analytics, accounting, proposals, chat_api, mcp, availability, actions
+from api.routers import admin, documents, masters, reports, setup as setup_router, bank_reconciliation, bank_statements, analytics, accounting, proposals, chat_api, mcp, availability, actions
 
 
 def load_plugins() -> None:
@@ -112,6 +112,7 @@ app.include_router(reports.router, prefix="/api")
 app.include_router(analytics.router, prefix="/api")
 app.include_router(setup_router.router, prefix="/api")
 app.include_router(bank_reconciliation.router, prefix="/api")
+app.include_router(bank_statements.router, prefix="/api")
 app.include_router(accounting.router, prefix="/api")
 app.include_router(admin.router, prefix="/api")
 app.include_router(chat_router, prefix="/api")