lambda-erp 1.3.3__tar.gz → 1.4.1__tar.gz

{lambda_erp-1.3.3 → lambda_erp-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lambda-erp
-Version: 1.3.3
+Version: 1.4.1
 Summary: Core ERP logic - accounting, sales, purchasing, inventory
 Author: TORUS INVESTMENTS AG
 License-Expression: Apache-2.0
@@ -9,6 +9,7 @@ Requires-Python: >=3.10
 Requires-Dist: bcrypt>=5
 Requires-Dist: defusedxml>=0.7
 Requires-Dist: fastapi>=0.115
+Requires-Dist: fonttools[woff]>=4.38
 Requires-Dist: holidays>=0.40
 Requires-Dist: httpx>=0.27
 Requires-Dist: jinja2>=3.1
@@ -16,6 +17,7 @@ Requires-Dist: openai>=1.0
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pypdf>=4.0
+Requires-Dist: pypdfium2>=4.30
 Requires-Dist: python-dateutil>=2.8
 Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-jose[cryptography]>=3.3
@@ -162,6 +164,7 @@ The result is booked in one step — chart of accounts, sensible default account
 - Custom analytics drafts via chat (persisted, shareable, editable)
 - Server-side aggregation tool for in-chat factual answers across large datasets
 - PDF / image attachment → add invoices, create quotations, etc. all directly by adding them in the chat
+- **PDF output with your own layouts** — every offer, order, invoice, purchase order, delivery note, proposal and reservation prints as a PDF. Layouts are HTML/CSS templates with your own images and fonts, edited in the settings or simply by asking the chat ("make the offer layout look like our letterhead"), previewed against real documents, then published as versions; submitted documents keep the exact layout they were issued with. See [`docs/pdf-output.md`](docs/pdf-output.md).
 - **Programmatic API** — drive the ERP from external systems with per-user, role-capped Bearer keys: a [chat API](docs/chat-api.md) (converse with the agent) and a [REST API](docs/rest-api.md) (documents, masters, reports — the same endpoints the web app uses, so a connector or sync job can create and submit documents directly). Both off by default; an admin enables each independently and issues keys.
 - **MCP server** — the ERP speaks the [Model Context Protocol](https://modelcontextprotocol.io) at `POST /api/mcp`, so **any MCP-capable agent (Claude, Codex, an IDE assistant) can drive it directly** — list/create/update/submit documents, manage master data, run reports — as *structured, validated tool calls*, not brittle screen-scraping or hand-written HTTP glue. The tool list is built from the live registries, so a plugin's own doctypes (e.g. a CRM's leads/contacts) are exposed automatically. It reuses the *same* Bearer keys and roles as the REST API — a viewer key is read-only, a manager key can write — so access is scoped, auditable, and off by default. In practice: point your assistant at your instance and ask "which invoices are overdue?" or "create a quotation for Acme with 3× SVC-SPARK" and it operates on real data, from wherever you already work. The API-keys settings page hands you ready-to-paste Claude and Codex config the moment you create a key.
 - Auth with admin/manager/viewer roles plus a public demo mode
@@ -176,7 +179,6 @@ The result is booked in one step — chart of accounts, sensible default account
 - Manufacturing (BOM, work orders)
 - HR / Payroll beyond the journal-entry workaround
 - Regional compliance packs (GST, VAT returns, etc.) - see below
-- PDF report creation directly inside the chat
 
 ---
 

{lambda_erp-1.3.3 → lambda_erp-1.4.1}/README.md

@@ -134,6 +134,7 @@ The result is booked in one step — chart of accounts, sensible default account
 - Custom analytics drafts via chat (persisted, shareable, editable)
 - Server-side aggregation tool for in-chat factual answers across large datasets
 - PDF / image attachment → add invoices, create quotations, etc. all directly by adding them in the chat
+- **PDF output with your own layouts** — every offer, order, invoice, purchase order, delivery note, proposal and reservation prints as a PDF. Layouts are HTML/CSS templates with your own images and fonts, edited in the settings or simply by asking the chat ("make the offer layout look like our letterhead"), previewed against real documents, then published as versions; submitted documents keep the exact layout they were issued with. See [`docs/pdf-output.md`](docs/pdf-output.md).
 - **Programmatic API** — drive the ERP from external systems with per-user, role-capped Bearer keys: a [chat API](docs/chat-api.md) (converse with the agent) and a [REST API](docs/rest-api.md) (documents, masters, reports — the same endpoints the web app uses, so a connector or sync job can create and submit documents directly). Both off by default; an admin enables each independently and issues keys.
 - **MCP server** — the ERP speaks the [Model Context Protocol](https://modelcontextprotocol.io) at `POST /api/mcp`, so **any MCP-capable agent (Claude, Codex, an IDE assistant) can drive it directly** — list/create/update/submit documents, manage master data, run reports — as *structured, validated tool calls*, not brittle screen-scraping or hand-written HTTP glue. The tool list is built from the live registries, so a plugin's own doctypes (e.g. a CRM's leads/contacts) are exposed automatically. It reuses the *same* Bearer keys and roles as the REST API — a viewer key is read-only, a manager key can write — so access is scoped, auditable, and off by default. In practice: point your assistant at your instance and ask "which invoices are overdue?" or "create a quotation for Acme with 3× SVC-SPARK" and it operates on real data, from wherever you already work. The API-keys settings page hands you ready-to-paste Claude and Codex config the moment you create a key.
 - Auth with admin/manager/viewer roles plus a public demo mode
@@ -148,7 +149,6 @@ The result is booked in one step — chart of accounts, sensible default account
 - Manufacturing (BOM, work orders)
 - HR / Payroll beyond the journal-entry workaround
 - Regional compliance packs (GST, VAT returns, etc.) - see below
-- PDF report creation directly inside the chat
 
 ---
 

{lambda_erp-1.3.3 → lambda_erp-1.4.1}/api/attachments.py

@@ -9,6 +9,7 @@ import time
 import uuid
 from typing import Optional
 
+import httpx
 import openpyxl
 from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
 from fastapi.responses import Response
@@ -17,6 +18,7 @@ from openai import OpenAI
 from lambda_erp.database import get_db
 from lambda_erp.utils import now
 from api.auth import require_role, get_current_user
+from api.llm_provider import client_kwargs
 from api.demo_limits import demo_max_attachment_bytes, is_demo_role
 
 logger = logging.getLogger(__name__)
@@ -56,10 +58,14 @@ STRUCTURED_TOOL_MIME_TYPES = {
     "application/xml", "text/xml", "application/zip", "application/x-zip-compressed",
 }
 
+# Font files, for PDF templates (add_attachment_to_pdf_template). The model gets
+# a one-line description, never the bytes.
+FONT_MIME_TYPES = {"font/ttf", "font/otf", "font/woff", "font/woff2"}
+
 ALLOWED_MIME_TYPES = {
     "image/png", "image/jpeg", "image/gif", "image/webp",
     "application/pdf",
-} | OFFICE_MIME_TYPES | TEXT_MIME_TYPES | STRUCTURED_TOOL_MIME_TYPES
+} | OFFICE_MIME_TYPES | TEXT_MIME_TYPES | STRUCTURED_TOOL_MIME_TYPES | FONT_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
@@ -81,6 +87,7 @@ _EXT_TO_MIME = {
     "pdf": "application/pdf",
     "png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg",
     "gif": "image/gif", "webp": "image/webp",
+    "ttf": "font/ttf", "otf": "font/otf", "woff": "font/woff", "woff2": "font/woff2",
 }
 _MIME_TO_EXT = {m: e for e, m in _EXT_TO_MIME.items()}
 
@@ -100,7 +107,6 @@ _OPENAI_FILE_TTL_SECONDS = 30 * 24 * 3600      # 30 days
 _OPENAI_FILE_REUSE_MARGIN = 300               # re-upload if within 5 min of expiry
 SPREADSHEET_ROW_WARN_LIMIT = 1000             # OpenAI augments ~1000 rows/sheet
 
-_openai_singleton: Optional[OpenAI] = None
 _expires_after_supported = True               # flips off if the API rejects it once
 
 # The single Office spreadsheet mime we can cheaply row-count (openpyxl).
@@ -108,12 +114,9 @@ _XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 
 
 def _openai_client() -> OpenAI:
-    """Lazily build a module-level OpenAI client for Files uploads (a separate
-    call from the chat completion; same OPENAI_API_KEY)."""
-    global _openai_singleton
-    if _openai_singleton is None:
-        _openai_singleton = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", ""))
-    return _openai_singleton
+    """An OpenAI client for Files uploads (a separate call from the chat
+    turn; same provider and key, see api/llm_provider.py)."""
+    return OpenAI(**client_kwargs(httpx.Timeout(60.0, connect=10.0)))
 
 
 def _create_openai_file(att: dict):
@@ -256,7 +259,7 @@ async def upload_attachment(
                 status_code=400,
                 detail=(f"Unsupported file type: {mime or ext or 'unknown'}. Allowed: images, PDF, "
                         "spreadsheets (Excel/CSV/ODS), documents (Word/OpenDocument), "
-                        "and structured bank files (XML/ZIP)."),
+                        "structured bank files (XML/ZIP) and fonts (TTF/OTF/WOFF/WOFF2)."),
             )
 
     chunks: list[bytes] = []
@@ -417,6 +420,16 @@ def build_multimodal_content(attachment: dict) -> dict:
                 "the conversation; use the dedicated bank-statement preview tool.]"
             ),
         }
+    if mime in FONT_MIME_TYPES:
+        from api.pdf_fonts import font_file_info
+        try:
+            font = font_file_info(attachment["data"])
+            what = f'family "{font["family"]}", style {font["style"]}, embedding: {font["embedding"]}'
+        except ValueError as exc:
+            what = str(exc)
+        return {"type": "text", "text": (
+            f"[Font file: {filename} ({what}; id {attachment['id']}). To print a PDF template with it, "
+            "call add_attachment_to_pdf_template with this attachment id.]")}
     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-1.3.3 → lambda_erp-1.4.1}/api/bootstrap.py

@@ -112,6 +112,7 @@ def bootstrap_demo() -> None:
             f"({DEMO_SIM_START} -> {DEMO_SIM_END}, seed={DEMO_SIM_SEED})",
             flush=True,
         )
+        from api.pdf_templates import pin_only
         from lambda_erp.simulation import HistoricalSimulator
 
         sim = HistoricalSimulator(
@@ -120,7 +121,10 @@ def bootstrap_demo() -> None:
             end=DEMO_SIM_END,
             seed=DEMO_SIM_SEED,
         )
-        sim.run(simulate_activity=True)
+        # Rendering an archive PDF per seeded offer would turn a ~3-minute
+        # boot into far longer than the host's startup window allows.
+        with pin_only():
+            sim.run(simulate_activity=True)
     else:
         print(f"[bootstrap] simulation data present ({qtn_count} quotations), skipping", flush=True)
 

{lambda_erp-1.3.3 → lambda_erp-1.4.1}/api/chat.py

@@ -17,6 +17,7 @@ import json
 import logging
 import os
 import re
+import time
 import traceback
 import uuid
 from datetime import date
@@ -38,6 +39,7 @@ from api.demo_limits import (
     is_demo_role,
     limiter as demo_limiter,
 )
+from api.llm_provider import client_kwargs, llm_configured, not_configured_message
 from api.providers import cost_of_openai_call, cost_of_transcription
 from api.routers.masters import create_master_record, update_master_record, delete_master_record
 from api.routers.analytics import DATASET_FILTER_DESCRIPTION
@@ -566,7 +568,7 @@ TOOLS = [
                     "include_meta": {"type": "boolean", "description": "Use true for complete lists or overviews: returns exact total and pagination/coverage metadata."},
                     "include_discarded": {"type": "boolean", "description": "Include discarded drafts when checking recent changes; default false."},
                     "doctype": {"type": "string", "enum": DOCUMENT_SLUGS, "description": "Document type slug"},
-                    "filters": {"type": "object", "description": "Optional filters on any column. Equality: {\"status\": \"Draft\", \"customer\": \"CUST-001\"}. Comparison (value = a 2-item array [op, value]): {\"grand_total\": [\">\", 100]}, {\"fit\": [\"!=\", \"A\"]}. Case-insensitive text substring: {\"customer_name\": [\"contains\", \"acme\"]}. NULL checks (1-item array): {\"fit\": [\"is null\"]}, {\"main_email\": [\"is not null\"]}. Allowed ops: =, !=, >, <, >=, <=, in, not in, contains, like, not like, is null, is not null. IN example: {\"type\": [\"in\", [\"call\", \"email\", \"note\"]]}. Free-text search: {\"search\": \"acme\"} matches the doctype's default text columns; narrow it with {\"search\": \"acme\", \"search_fields\": [\"company_name\", \"tags\"]}.", "default": {}},
+                    "filters": {"type": "object", "description": "Optional filters on any column. Equality: {\"status\": \"Draft\", \"customer\": \"CUST-001\"}. Comparison (value = a 2-item array [op, value]): {\"grand_total\": [\">\", 100]}, {\"fit\": [\"!=\", \"A\"]}. Case-insensitive text substring: {\"customer_name\": [\"contains\", \"acme\"]}. NULL checks (1-item array): {\"fit\": [\"is null\"]}, {\"main_email\": [\"is not null\"]}. Allowed ops: =, !=, >, <, >=, <=, in, not in, contains, like, not like, is null, is not null. IN example: {\"type\": [\"in\", [\"call\", \"email\", \"note\"]]}. Free-text search: {\"search\": \"acme\"} matches the doctype's default text columns, and on documents with lines (offers, orders, invoices, delivery notes, receipts, stock entries, subscriptions) also any line's item code, item name or description; narrow the document's own columns with {\"search\": \"acme\", \"search_fields\": [\"company_name\", \"tags\"]}.", "default": {}},
                     "order_by": {"type": "string", "description": "Optional column to sort by. Defaults to the time_filter field when supplied, otherwise 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},
@@ -1074,6 +1076,36 @@ TOOLS = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "inspect_pdf_fonts",
+            "description": "List the exact fonts an uploaded PDF uses (read from the file, not guessed from its look), or identify an uploaded font file, and say for each whether PDF templates can print with it: installed, metric_compatible (another name with the same letter widths) or missing (falls back). Use it before styling a PDF template after a reference PDF.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "attachment_id": {"type": "string", "description": "The PDF or font file attachment (from list_chat_attachments)."},
+                },
+                "required": ["attachment_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "add_attachment_to_pdf_template",
+            "description": "Add a font file (ttf, otf, woff, woff2) or image (png, jpg, gif, webp) the user uploaded in this chat to a PDF template's working copy as an asset. Reference it by its file name in the template: url(\"name.woff2\") in @font-face (the result includes a ready @font-face rule), <img src=\"logo.png\">. Only add fonts the user may use: a commercial font needs a licence that allows embedding it in PDFs; mention that when a user uploads one.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "template": {"type": "string", "description": "PDF template id (e.g. PDFT-0001)."},
+                    "attachment_id": {"type": "string", "description": "The uploaded font or image (from list_chat_attachments)."},
+                    "filename": {"type": "string", "description": "Asset file name to use in the template; defaults to the upload's name."},
+                },
+                "required": ["template", "attachment_id"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -1570,6 +1602,11 @@ def _handle_list_documents(args):
         return {"error": str(exc)}
 
 
+# Tools whose result is a stored PDF export the reply may link to; the reply
+# check in run_session_turn rejects any other /documents/.../pdf link.
+PDF_EXPORT_TOOLS = ("generate_document_pdf", "preview_pdf_template")
+
+
 def _handle_generate_document_pdf(args, user=None):
     from api.pdf_exports import create_pdf_export
     from api.pdf_contract import PDFError
@@ -1989,6 +2026,56 @@ def _handle_retrieve_chat_attachment(args, session_id: str | None = None, user_i
     }
 
 
+def _chat_attachment(args, session_id, user_id):
+    if not session_id or not user_id:
+        return None, {"error": "No active chat session for attachments."}
+    from api.attachments import get_attachments_by_ids
+    atts = get_attachments_by_ids([args.get("attachment_id") or ""], user_id)
+    if not atts:
+        return None, {"error": "Attachment not found or access denied."}
+    return atts[0], None
+
+
+def _handle_inspect_pdf_fonts(args, session_id: str | None = None, user_id: str | None = None):
+    from api import pdf_fonts
+    from api.attachments import FONT_MIME_TYPES
+    att, error = _chat_attachment(args, session_id, user_id)
+    if error:
+        return error
+    try:
+        if att["mime_type"] == "application/pdf":
+            fonts = pdf_fonts.fonts_in_pdf(att["data"])
+        elif att["mime_type"] in FONT_MIME_TYPES:
+            info = pdf_fonts.font_file_info(att["data"])
+            fonts = [{**info, **pdf_fonts.availability(info["family"]),
+                      "note": "Add it to a template with add_attachment_to_pdf_template to print with this exact file."}]
+        else:
+            return {"error": f"{att['filename']} is neither a PDF nor a font file."}
+    except Exception as exc:  # noqa: BLE001 — a malformed upload is the user's file, not a server fault
+        return {"error": f"Could not read the fonts of {att['filename']}: {exc}"}
+    return {"filename": att["filename"], "fonts": fonts, "installed_fonts": list(pdf_fonts.installed_families())}
+
+
+def _handle_add_attachment_to_pdf_template(args, user=None, session_id: str | None = None,
+                                           user_id: str | None = None):
+    from api import pdf_templates
+    att, error = _chat_attachment(args, session_id, user_id)
+    if error:
+        return error
+    filename = args.get("filename") or re.sub(r"[^A-Za-z0-9._-]+", "-", att["filename"]).strip("-")
+    try:
+        result = pdf_templates.add_pdf_template_asset(args.get("template") or "", filename, att["data"], user)
+    except (ValueError, pdf_templates.PDFError) as exc:
+        return {"error": str(exc)}
+    out = {"template": result["template"], "asset": filename, "assets": result["assets"]}
+    if result.get("font"):
+        out["font"] = result["font"]
+        out["note"] = "Add the css rule to the template's <style> and use the family in font-family."
+    else:
+        out["note"] = f'Reference it as <img src="{filename}"> or url("{filename}").'
+    return out
+
+
 def _load_camt_chat_attachments(args, user_id: str | None):
     attachment_ids = args.get("attachment_ids") or []
     if not user_id:
@@ -2348,6 +2435,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,
+    "inspect_pdf_fonts": _handle_inspect_pdf_fonts,
+    "add_attachment_to_pdf_template": _handle_add_attachment_to_pdf_template,
     "preview_bank_statement_attachments": _handle_preview_bank_statement_attachments,
     "import_bank_statement_attachments": _handle_import_bank_statement_attachments,
     "list_bank_reconciliation_queue": _handle_list_bank_reconciliation_queue,
@@ -2719,6 +2808,10 @@ The `remarks` (Notes / Terms) field on quotations, sales orders, and invoices re
 - A line starting with `>>` is a price line, split by the FIRST `|` pipe: the text BEFORE the pipe goes in the left (frequency) column, the text AFTER it in the right (amount) column — both placed literally as you write them, NOT interpreted (it does not know "Monatlich" is a frequency or that "CHF 380" is a number). Omit the pipe to put everything in the amount column. The two columns line up with the line-items table's frequency/amount columns, so use it for a separately- or recurring-billed item, e.g. `>> Monatlich | CHF 380.—`.
 - Separate blocks with a blank line; a single newline is just a line break.
 Plain text (no special characters) still renders fine, so only reach for the markup when it improves a customer-facing note.
+Quotations also have `intro_text`: the opening text (greeting, "Gerne unterbreiten wir Ihnen …"), printed above the line items with the same markup; `remarks` is the closing text / conditions after the totals. Put each in its own field. Both may use placeholders filled in at print time: {{ customer_name }}, {{ valid_till }}, {{ transaction_date }}, {{ name }}, {{ company }}, {{ currency }}. New offers start with the default texts (get_pdf_text_defaults / set_pdf_text_defaults); sending a field explicitly overrides its default.
+
+### Deductions on a line
+To take an amount off one position (already invoiced, credited from a previous project, a project rebate), keep the position at its full price and put the deduction on that same line: `price_list_rate` = full price per unit, `discount_amount` = deduction per unit, `discount_label` = its printed text (e.g. "Abzüglich bereits verrechnet (Rechnung SINV-0003)"). The line then counts the net (rate = price_list_rate − discount_amount); the PDF prints the full price and the deduction as an italic sub-line. A deduction can't exceed its position's price, so a line never goes negative and keeps its tax rate. Sending only `rate` with a new deduction takes that rate as the full price. To remove one, set `discount_amount` 0, `discount_label` empty and `rate` back to the full price. The deduction is carried into the sales order and invoice. There are no negative lines: a deduction always belongs to a position.
 
 ### Internal notes (never printed)
 `remarks` is PRINTED and goes to the customer or supplier. Internal team remarks ("customer disputes line 2", "@Anna please check the price") belong in an internal note on the record instead: `add_record_note` (doctype = the record type slug, e.g. `sales-invoice` or `customer`; record_id = its name), read with `list_record_notes`, change with `update_record_note` / `delete_record_note`. Every document and master type supports them; they appear in the record's "Internal notes" card and never change the record. To notify a colleague, first `search_mention_users` and put their exact `mention_text` in the body. Never put internal remarks into `remarks`, and never copy internal notes into customer-facing text.
@@ -2942,7 +3035,7 @@ Users can attach PDFs and images (receipts, bills, contracts, screenshots) to th
 # GPT-6.1 Sol acts as the planner/orchestrator. When it decides a report needs
 # a custom analytics view it calls the create/update custom analytics tools.
 # Those handlers make a separate, narrowly prompted GPT-6.1 Sol call for the bounded
-# declarative report spec. Both roles use the existing OPENAI_API_KEY.
+# declarative report spec. Both roles use the same provider and key (api/llm_provider.py).
 # ---------------------------------------------------------------------------
 
 
@@ -3154,9 +3247,8 @@ def _generate_report_spec_via_openai(
     user_role: str | None = None,
     session_id: str | None = None,
 ) -> dict:
-    api_key = os.environ.get("OPENAI_API_KEY", "")
-    if not api_key or api_key == "sk-your-key-here":
-        raise RuntimeError("OPENAI_API_KEY is not configured")
+    if not llm_configured():
+        raise RuntimeError(not_configured_message())
 
     model = _report_specialist_model()
 
@@ -3186,10 +3278,7 @@ def _generate_report_spec_via_openai(
     )
     user_msg = "\n\n".join(user_parts)
 
-    client = OpenAI(
-        api_key=api_key,
-        timeout=httpx.Timeout(120.0, connect=10.0),
-    )
+    client = OpenAI(**client_kwargs(httpx.Timeout(120.0, connect=10.0)))
     validation_feedback: str | None = None
     max_attempts = 2
 
@@ -3292,28 +3381,30 @@ def _title_model() -> str:
     return os.environ.get("LAMBDA_ERP_TITLE_MODEL") or TITLE_MODEL
 
 
+# Background title tasks, kept referenced so they aren't garbage-collected
+# before they finish.
+_title_tasks: set[asyncio.Task] = set()
+
+
 async def generate_title(
     session_id: str,
     user_message: str,
-    assistant_message: str,
+    assistant_message: str = "",
     client_ip: str | None = None,
     user_role: str | None = None,
 ):
-    """Generate a short title for the chat based on the first exchange.
+    """Generate a short title for the chat from its first message.
 
-    Called after the first assistant reply. Runs in the background so it
-    doesn't block the response.
+    Started in the background as soon as the first message arrives, so the
+    title shows up while the reply is still being written. Without a text
+    message (attachments only) it runs after the first reply and uses that too.
     """
-    api_key = os.environ.get("OPENAI_API_KEY", "")
-    if not api_key or api_key == "sk-your-key-here":
+    if not llm_configured():
         return
 
     title_model = _title_model()
     try:
-        client = OpenAI(
-            api_key=api_key,
-            timeout=httpx.Timeout(30.0, connect=5.0),
-        )
+        client = OpenAI(**client_kwargs(httpx.Timeout(30.0, connect=5.0)))
         reservation_id = None
         if is_demo_role(user_role):
             _blocked, reservation_id = demo_limiter.reserve(
@@ -3325,14 +3416,18 @@ async def generate_title(
                 return
 
         settled = False
+        started = time.monotonic()
+        exchange = f"User: {user_message[:200]}"
+        if assistant_message:
+            exchange += f"\nAssistant: {assistant_message[:200]}"
         try:
             # Responses API with low effort: GPT-6 models reason, and the
             # output budget must leave room for that before the title itself.
             response = await asyncio.to_thread(
                 client.responses.create,
                 model=title_model,
-                instructions="Generate a very short title (3-6 words, no quotes) for this chat based on the first exchange. Just the title, nothing else.",
-                input=f"User: {user_message[:200]}\nAssistant: {assistant_message[:200]}",
+                instructions="Generate a very short title (3-6 words, no quotes) for this chat based on its first message. Just the title, nothing else.",
+                input=exchange,
                 max_output_tokens=400,
                 reasoning={"effort": "low"},
             )
@@ -3353,6 +3448,8 @@ async def generate_title(
             title = (response.output_text or "").strip().strip('"\'')[:120]
             if title:
                 update_session_title(session_id, title)
+                print(f"[chat_title] model={title_model} session_id={session_id} "
+                      f"ms={int((time.monotonic() - started) * 1000)}", flush=True)
             else:
                 logger.warning("[chat_title] model=%s returned no title (status=%s)",
                                title_model, getattr(response, "status", None))
@@ -3473,8 +3570,11 @@ def _responses_msg_content(content):
         if ptype == "text":
             parts.append({"type": "input_text", "text": p.get("text", "")})
         elif ptype == "image_url":
-            url = (p.get("image_url") or {}).get("url")
-            parts.append({"type": "input_image", "image_url": url})
+            image = p.get("image_url") or {}
+            part = {"type": "input_image", "image_url": image.get("url")}
+            if image.get("detail"):
+                part["detail"] = image["detail"]
+            parts.append(part)
         elif ptype == "file":
             f = p.get("file") or {}
             item = {"type": "input_file"}
@@ -3601,15 +3701,14 @@ async def run_thinking_loop(
     declarative-spec step to a separate narrowly prompted GPT-6.1 Sol call. We emit an
     `llm_provider` event around that delegation so the UI can surface it.
     """
-    openai_api_key = os.environ.get("OPENAI_API_KEY", "")
-    if not openai_api_key or openai_api_key == "sk-your-key-here":
-        await on_event({"type": "error", "content": "Error: OPENAI_API_KEY is not configured. Please set it in the .env file."})
+    if not llm_configured():
+        await on_event({"type": "error", "content": f"Error: {not_configured_message()}. Set it in the environment (.env)."})
         return
 
-    openai_client = OpenAI(
-        api_key=openai_api_key,
-        timeout=httpx.Timeout(120.0, connect=10.0),
-    )
+    openai_client = OpenAI(**client_kwargs(
+        httpx.Timeout(120.0, connect=10.0),
+        erp_user=user_info.get("name") if user_info else None,
+    ))
 
     # Closures below read through this reference so a live role/key refresh
     # immediately affects resource-aware handlers as well as the shared policy.
@@ -3654,6 +3753,9 @@ 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["inspect_pdf_fonts"] = lambda args: _handle_inspect_pdf_fonts(args, session_id, user_id_for_tools)
+        tool_handlers["add_attachment_to_pdf_template"] = lambda args: _handle_add_attachment_to_pdf_template(
+            args, principal_ref[0], session_id, user_id_for_tools)
         tool_handlers["preview_bank_statement_attachments"] = (
             lambda args: _handle_preview_bank_statement_attachments(args, user_id_for_tools)
         )
@@ -3844,9 +3946,13 @@ async def run_thinking_loop(
             # Pull any multimodal content out of the tool result before serializing.
             # retrieve_chat_attachment returns a {"_multimodal_content": {...}} block
             # which we inject as a fresh user message so the LLM can "see" the file.
+            # view_pdf_pages returns rendered pages under "_images" the same way;
+            # they are shown to the model for this turn and never persisted.
             multimodal_block = None
+            page_images = None
             if isinstance(result, dict):
                 multimodal_block = result.pop("_multimodal_content", None)
+                page_images = result.pop("_images", None)
 
             result_str = json.dumps(result, default=str)
             summary = result_str[:500] + "..." if len(result_str) > 500 else result_str
@@ -3871,7 +3977,7 @@ async def run_thinking_loop(
                 event_payload["report_id"] = result["id"]
             if fn_name == "generate_document_pdf":
                 event_payload["document_request"] = {key: fn_args.get(key) for key in ("doctype", "name")}
-            if success and fn_name == "generate_document_pdf" and isinstance(result, dict) and result.get("artifact_id"):
+            if success and fn_name in PDF_EXPORT_TOOLS and isinstance(result, dict) and result.get("artifact_id"):
                 event_payload["document"] = result
             if session_id:
                 _save_tool_trace(session_id, "tool_result", {**event_payload, "result": result})
@@ -3885,6 +3991,9 @@ async def run_thinking_loop(
 
             if multimodal_block:
                 pending_multimodal.append(multimodal_block)
+            if page_images:
+                from api.pdf_pages import image_parts
+                pending_multimodal.extend(image_parts(page_images))
 
         # After this batch of tool calls, inject any retrieved attachments as
         # a new user message so the LLM can actually see them on the next turn.
@@ -3892,7 +4001,7 @@ async def run_thinking_loop(
             messages.append({
                 "role": "user",
                 "content": [
-                    {"type": "text", "text": "Here are the attachments you requested:"},
+                    {"type": "text", "text": "Here are the attachments and PDF pages you requested:"},
                     *pending_multimodal,
                 ],
             })
@@ -3962,14 +4071,14 @@ VOICE_TRANSCRIBE_PROMPT = (
 _MIN_TRANSCRIBE_BYTES = 1500  # ~1s of webm/opus at the ~1.5 KB/s we assume below
 
 
-def transcribe_audio(audio_bytes: bytes, audio_format: str, api_key: str) -> str:
+def transcribe_audio(audio_bytes: bytes, audio_format: str, erp_user: str | None = None) -> str:
     """Transcribe audio to text via OpenAI gpt-4o-transcribe.
 
     Returns the transcript, or "" when the model detects silence/near-silence
     (empty result or a prompt-echo hallucination on a near-silent clip).
     Raises on an actual API error so the caller can surface it.
     """
-    client = OpenAI(api_key=api_key, timeout=httpx.Timeout(60.0, connect=10.0))
+    client = OpenAI(**client_kwargs(httpx.Timeout(60.0, connect=10.0), erp_user=erp_user))
 
     audio_file = io.BytesIO(audio_bytes)
     audio_file.name = f"voice.{audio_format or 'webm'}"
@@ -4040,10 +4149,34 @@ async def run_session_turn(
     Hooks (all optional, async):
       - ``on_event(event)``            streamed loop events (WS -> socket; REST -> no-op)
       - ``on_assistant_message(sid, content)``  fired after the reply is persisted
-      - ``on_title(sid, title)``       fired after a first-reply title is generated
+      - ``on_title(sid, title)``       fired once the first message's title is generated
     """
     is_first_reply = count_assistant_messages(session_id) == 0
 
+    def start_title(assistant_text: str = ""):
+        async def _gen_and_notify():
+            await generate_title(
+                session_id,
+                user_content,
+                assistant_text,
+                client_ip=client_ip,
+                user_role=(user_info or {}).get("role"),
+            )
+            if on_title:
+                session = get_session(session_id)
+                if session:
+                    await on_title(session_id, session["title"])
+        task = asyncio.create_task(_gen_and_notify())
+        _title_tasks.add(task)
+        task.add_done_callback(_title_tasks.discard)
+
+    # Title the chat from the first message right away, in parallel with the
+    # reply: waiting for the whole reply left "New Chat" in the sidebar for
+    # the length of the turn plus the title call.
+    title_started = is_first_reply and bool((user_content or "").strip())
+    if title_started:
+        start_title()
+
     messages = [{"role": "system", "content": build_system_prompt(user_info, channel=channel)}]
 
     if replay_history:
@@ -4077,7 +4210,7 @@ async def run_session_turn(
     generated_files = []
 
     async def pdf_events(event):
-        if event.get('type') == 'tool_result' and event.get('tool') == 'generate_document_pdf' and event.get('success') and event.get('document'):
+        if event.get('type') == 'tool_result' and event.get('tool') in PDF_EXPORT_TOOLS and event.get('success') and event.get('document'):
             generated_files.append(event['document'])
         await on_event(event)
 
@@ -4111,20 +4244,8 @@ async def run_session_turn(
                 await on_assistant_message(session_id, assistant_content)
             break
 
-    if is_first_reply and assistant_content:
-        async def _gen_and_notify():
-            await generate_title(
-                session_id,
-                user_content,
-                assistant_content,
-                client_ip=client_ip,
-                user_role=(user_info or {}).get("role"),
-            )
-            if on_title:
-                session = get_session(session_id)
-                if session:
-                    await on_title(session_id, session["title"])
-        asyncio.create_task(_gen_and_notify())
+    if is_first_reply and not title_started and assistant_content:
+        start_title(assistant_content)
 
     return assistant_content
 
@@ -4454,11 +4575,10 @@ async def chat_websocket(
                 # Voice → text: transcribe a recorded clip and return the text
                 # for the composer. No LLM turn here — the user reviews/edits
                 # the text and sends it like any typed message.
-                openai_api_key = os.environ.get("OPENAI_API_KEY", "")
-                if not openai_api_key or openai_api_key == "sk-your-key-here":
+                if not llm_configured():
                     await send_event(
                         "transcription_result", request_id=request_id,
-                        success=False, error="Speech-to-text is not available (OPENAI_API_KEY not configured).",
+                        success=False, error=f"Speech-to-text is not available ({not_configured_message()}).",
                     )
                     continue
 
@@ -4491,7 +4611,7 @@ async def chat_websocket(
 
                 try:
                     text = await asyncio.to_thread(
-                        transcribe_audio, audio_bytes, audio_format, openai_api_key,
+                        transcribe_audio, audio_bytes, audio_format, ws_user_id,
                     )
                 except Exception as e:
                     logger.warning("Transcription failed: %s", e)