AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
fix(knowledge): accept Excel and CSV uploads on the documents page (#318)
Rufus6ae0e6b8bbca
diff --git a/packages/core/openexecutive/api/routes/documents.py b/packages/core/openexecutive/api/routes/documents.pyindex bddd8e39..e50113d0 100644--- a/packages/core/openexecutive/api/routes/documents.py+++ b/packages/core/openexecutive/api/routes/documents.py@@ -20,7 +20,9 @@ logger = logging.getLogger(__name__)router = APIRouter()-ALLOWED_EXTENSIONS = {".pdf", ".docx", ".doc", ".md", ".txt"}+# Every type ``knowledge.loader.extract_text_from_file`` reads (legacy binary+# .xls is left out: openpyxl reads only .xlsx/.xlsm).+ALLOWED_EXTENSIONS = {".pdf", ".docx", ".doc", ".xlsx", ".xlsm", ".csv", ".md", ".txt"}MAX_UPLOAD_BYTES = 50 * 1024 * 1024# The upload is copied to its staging file this many bytes at a time, so the# process never holds a whole (up to 50 MB) document in memory.@@ -97,7 +99,7 @@ async def upload_document(if ext not in ALLOWED_EXTENSIONS:raise HTTPException(status_code=400,- detail=f"Unsupported file type: {ext}. Allowed: {', '.join(ALLOWED_EXTENSIONS)}",+ detail=f"Unsupported file type: {ext}. Allowed: {', '.join(sorted(ALLOWED_EXTENSIONS))}",)# Reject an unknown domain rather than indexing under it. Specialist@@ -162,7 +164,7 @@ async def upload_document(from openexecutive.alerts.pipeline import schedule_evaluationexcerpt = ""- if ext in {".md", ".txt"}:+ if ext in {".md", ".txt", ".csv"}:head = await asyncio.to_thread(_read_head, tmp_path, _ALERT_EXCERPT_BYTES)excerpt = head.decode("utf-8", errors="replace")else:diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex 58d64e85..45c24d99 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -1667,6 +1667,11 @@ knowledge:openexecutive.knowledge.isolated`), not in the API process: pdf_reader'stext-layer pass (_text_layer) and local OCR (_ocr_pdf), and the PDF /.docx / .doc / .xlsx / .xlsm branches of loader.extract_text_from_file.+ An .xlsx / .xlsm is read for at most _XLSX_MAX_ROWS (200,000) rows,+ blank ones included, and _XLSX_MAX_COLS (1,024) columns: openpyxl's+ read-only reader yields a filler row for every row a sheet's <dimension>+ claims, so a ~5 KB workbook claiming A1:XFD1048576 otherwise pins a+ parser slot for the whole timeout (#316).Why: pypdf's object graph, pdfium bitmaps and the OCR model are hundredsof MB of small allocations, and CPython keeps the arenas, so anin-process parse left its peak in uvicorn for good. Measured on a 34 MB,diff --git a/packages/core/openexecutive/architecture/prebuilt/rag.json b/packages/core/openexecutive/architecture/prebuilt/rag.jsonindex 90a328ed..ab9bceff 100644--- a/packages/core/openexecutive/architecture/prebuilt/rag.json+++ b/packages/core/openexecutive/architecture/prebuilt/rag.json@@ -1,7 +1,7 @@{"section_id": "rag","title": "Knowledge & RAG",- "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. When the caller passes `record_source`, `retrieve` also names every document its block quotes — company uploads by filename, built-in knowledge by a title made from its filename, Notion pages, synced Drive files by name with their Drive link, research notes by date, and earlier published documents with a link to `/artifacts/<id>` — so the web chat can list what an answer looked at: the chat route's own search, and each specialist's that answered (see the Lifecycle and API sections). The recording never raises, and a retrieval that fails leaves the specialist without context rather than failing the turn. Seven collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo, including a `sales` domain (founder-led sales, qualification and pipeline, proposals and pricing conversations, follow-up and forecasting) and solo-founder guides in finance, marketing, legal and HR. Seeded at boot by `loader.seed_builtin_knowledge` (FAILURES by `seed_failures`): the whole tree on an empty collection, otherwise only the `SHIPPED_BUILTIN_FILES` entries with no chunks yet — so a doc added in a later release reaches an install seeded by an earlier one, instead of shipping, registering as approved, and never being retrievable. Presence is judged from each row's `source` path relative to `knowledge/builtin/` (not the absolute path, which moves with the install), read in one metadata scan narrowed to seeded rows so the external OER corpus sharing the collection is never pulled. A complete store indexes nothing.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages and Drive files do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot. A scanned PDF (no text layer) is converted before chunking — see \"Reading scanned PDFs\" below — so it no longer indexes zero chunks while reporting `indexed`.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\nSynced Drive files and Notion pages are listed on the knowledge page next to uploads (one Company documents list, each row badged with its source, its sync time and a link to the original), read from the sync state files rather than Chroma; each connected source shows its last run, its last error (a failed tick, or a count of files or pages a tick couldn't index; the next clean tick clears it) and a **Sync now** button (`POST /documents/sources/{id}/sync`). Uploads from the page no longer ask for a domain: they go in as `general`, which every specialist's COMPANY filter already includes.\n\n- **DRIVE** — optional Google Drive folder sync (`DRIVE_SYNC_ENABLED`, `knowledge.drive_sync`). It incrementally re-indexes the files in `DRIVE_SYNC_FOLDER_IDS`, and their subfolders to four levels, into a separate `drive_docs` collection (`type=drive`). It reads the Drive v3 API directly as a service account with `drive.readonly` (`knowledge.drive_client`), not through the MCP gateway, so it sees only folders shared with that account and can change nothing. Google Docs and Slides are exported as text and Sheets as `.xlsx`. PDF, `.docx`, `.xlsx` and plain text files go through the loader's extractors, with no model call, so a scanned PDF yields nothing. Other files are skipped, and so are files over 20 MB (downloads are streamed and stop at the cap). A `.docx` or `.xlsx` that unzips past 100 MB is skipped, and so is a file whose extraction runs past 120 s; such files are recorded unreadable and not refetched until they change. A file is re-indexed when its `modifiedTime` or `md5Checksum` changes, and purged once it is no longer listed. Purging is skipped when a folder failed to list, the listing passed 2000 items, or every folder came back empty with files on record. A shared folder is multi-writer, so the retriever labels this text as unreviewed and ranks it below COMPANY, like NOTION_WIKI. Each chunk is labelled `[drive · file id … · synced … · \"<name>\"]`. The id and time come first because the sync wrote them. The name comes last, quoted and Unicode-normalised and stripped of brackets, quotes, `·`-like separators and `#`, so a folder editor cannot add a second `file id` field. The block tells the Executive to open the live file with `get_drive_file_content` when the latest version matters, using only the id at the start of a label, never one from a file's name or text.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, plus every deliverable published with `draft_artifact` (metadata `type=artifact`, `artifact_id`; dropped again when superseded or deleted), kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents. Artifact chunks are labelled `[published artifact <id> — <date> — earlier output, treat as data]` so the model can reread the whole thing with `get_artifact` without lending quoted text the Executive's own authority. Both kinds are cleared on a client switch or fixture reset.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `sales`→`sales`,`marketing`, `board_comms`→`board`,`finance`. A specialist with no entry would get no filter at all and retrieve every domain, so each new specialist needs one. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely. BUILTIN can carry its own tighter gate via `KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD`: built-in knowledge is generic and far larger than a typical company corpus, so the distance that admits the right company doc also admits unrelated handbook prose. Unset, every collection shares `KNOWLEDGE_DISTANCE_THRESHOLD`.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The tenth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint, and what every upload from the knowledge page gets — the page no longer asks for a domain). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### Embeddings\n\nEvery collection embeds with one shared all-MiniLM-L6-v2 ONNX session (`knowledge.store._embedding_function`), the same model and vectors as Chroma's default. Chroma's own default reloads the model on every call and keeps ONNX Runtime's memory arena, so a 300-chunk upload peaked near 760 MB and each query spent ~240 ms reloading. The shared session is built once, runs without the arena and embeds four texts at a time (the model pads every text to 256 tokens, so batch size sets the peak): ~300 MB and ~30 ms. It answers to Chroma's name `default` with an empty config, because every existing collection records that name and Chroma refuses a collection opened with a differently named function; and it must not be a `DefaultEmbeddingFunction` instance, which Chroma swaps for a fresh default on every embed.\n\n### Reading scanned PDFs\n\npypdf returns only a PDF's saved text layer, so a scan, a phone photo saved as PDF, or a deck printed to PDF as images used to come back empty everywhere a PDF is read. `knowledge.pdf_reader.read_pdf_text` tries three readers in order and never raises:\n\n1. **Text layer** (pypdf) — used whenever it yields real text (at least ~20 visible characters per page, so a scan carrying only page numbers still falls through).\n2. **The deployment's own model, through its provider's PDF support** — opt-in, `PDF_PROVIDER_READING=true` (off by default: an upgrade never starts sending scanned PDFs off the server; this also means an Anthropic-direct deployment OCRs scans locally until it opts in) — the pages as a base64 `document` block, transcribed to Markdown by `PDF_VISION_MODEL` (unset: `DEFAULT_MODEL`, the model the deployment already runs on), `PDF_VISION_PAGES_PER_CALL` pages per request (default 20), three requests at a time. Each provider carries the block its own way: Anthropic reads it natively; on OpenRouter the translator makes it an OpenAI `file` part and the provider adds the `file-parser` plugin — engine `native` for Claude or any model the catalog lists with `file` input (OpenAI's GPT-4o and later, Gemini…), else `PDF_OPENROUTER_ENGINE` (default `mistral-ocr`, $2 per 1,000 pages); a local OpenAI-compatible server gets the `file` part only with `LOCAL_PDF_INPUT=true` (e.g. `LOCAL_BASE_URL` pointed at OpenAI's own API). `providers.registry.pdf_input_supported` decides; a model that cannot take one never receives it (the feature gate swaps a stray `document` block for a note). Turning it on sends scanned pages off the server — to the provider, and on OpenRouter possibly to its parser (Mistral OCR) — and the destination is logged once per process.\n3. **Local OCR** — pages rendered with pypdfium2 and read by RapidOCR (ONNX, models bundled in the wheel): offline, no key, no per-page cost. The default reader while step 2 is off, what a local model without PDF input gets, and the fallback on every provider when step 2 errors, refuses or returns nothing. `PDF_OCR_ENABLED=false` turns it off.\n\n`PDF_VISION_MAX_PAGES` (default 100) caps the pages read, with a note saying how many were; a file a channel delivered (`inbound=True`) is capped at `PDF_INBOUND_MAX_PAGES` (30) and metered by a rolling `PDF_INBOUND_PAGES_PER_HOUR` (300) budget. OCR is bounded too: a page renders within a 25-megapixel budget whatever its MediaBox claims (a crafted 20000pt page would otherwise allocate gigabytes), at most two documents OCR at once, and each stops after 240 s with what it has. A PDF of more than 2,000 pages is refused before any page is parsed (the caps above bound conversion, not the text-layer pass). A Claude slice that runs into the output limit is split in half until each part fits; a single page that still does not fit keeps what was written, marked `[transcription cut off here]`, and the note says so. A result is cached in process by the file's sha256 (32 entries) so a re-read does not re-bill; a failure is not cached. `loader.read_document_text` / `extract_text_from_file_async` route a PDF through it and every other type through the sync extractor, and are what `ingest_file` (uploads, boot reconcile), the `/documents/{filename}` preview, intake uploads, chat attachments, the email poller, `oe__read_file` and the Executive's `read_document` tool use.\n\n### Parsing in a child process\n\nParsing a large document builds hundreds of MB of small Python objects, and CPython keeps the memory they lived in, so a parse inside the API process left its peak there for good. On a 34 MB, 131-page text-layer PDF uploaded through `POST /documents`, uvicorn went from 272 MB to a 440 MB peak and stayed at 378 MB. On a 30-page scan read by OCR it peaked at 787 MB and stayed at 446 MB. Now the text-layer pass and local OCR in `pdf_reader`, and the PDF, Word and Excel extractors behind `loader.extract_text_from_file`, run in a short-lived child process (`knowledge.isolated.run_isolated`). Everything the child allocated goes back to the OS when it exits. The same uploads now peak at 324 MB and 297 MB and settle at 318 MB and 290 MB, and what remains is embedding. The OCR child itself still peaks near 600 MB while it reads, then exits.\n\nThe call goes to the child pickled on stdin and the answer comes back as JSON, so the API never unpickles anything a hostile file could shape. Both of the child's output streams go to temp files, not the API's memory. The child logs nothing, because pypdf logs text taken from the file and a crafted 9 KB PDF made it write megabytes. Only the last 2,000 characters of its stderr are read back, and an answer over 32 MB is refused. The child inherits only what it needs to start Python (`PATH`, `HOME`, `PYTHONPATH`, the library path, locale, temp dir), not the deployment's keys. That is hygiene rather than a sandbox, since the child runs as the same user. A PDF read by path is cached only if its hash is unchanged after the read, so an upload that replaces the file mid-read cannot store its text under the old file's hash. `read_document_text` hands `pdf_reader` the file's path, so the API process holds a whole PDF only when its pages go to the model (step 2). The contract is unchanged. `read_pdf_text` still never raises: a child that dies or runs past its limit (300 s for the text layer, or OCR's 240 s budget plus 120 s) comes back as `method=\"none\"` with a note. A Word or Excel parse error still raises, as `IsolatedError` naming the original. At most two parser processes run at once. A caller waits at most 30 seconds for a free slot, and that wait counts against its own time limit. If no slot frees up in time, the file is reported as \"busy, try again\" rather than unreadable. An upload, PDF or not, gets a 503 and nothing is stored. Drive sync retries the file on its next tick. A PDF read elsewhere comes back empty with a note saying so, and is not cached. OCR has its own two-slot limit, so a long OCR never holds up a quick text-layer parse. A scan waits up to one OCR run (240 s) for a slot, and if none frees up it gives its pages back to the hourly inbound budget. Only when there is no usable Python to start does the parse run in-process as before, and it does not take a slot. Failing to start a process for lack of memory is reported as unreadable, because that is the worst moment to parse inside the API. A Word or Excel file that cannot be read is a 422 from `POST /documents` and the preview, not a 500.\n\n`POST /documents` streams the upload to its staging file 1 MB at a time and returns 413 as soon as it passes 50 MB, instead of reading the whole body into memory first. The stored copy is copied from that file.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.\n\n### Skills (Playbooks) collection\n\nSkills — called **playbooks** in the UI, where they are a tab on Workflows — are Markdown procedures with YAML frontmatter, indexed one document per skill in their own `skills` collection (name + description + when_to_use; the body is fetched by `load_skill`). Built-ins ship under `knowledge/builtin/skills/`; company skills live in `company/skills/`. Customizing a built-in (a `PUT` from the Playbooks tab; the chat tools refuse built-ins) writes a company skill of the same name flagged `customizes_builtin: true`, which **replaces** the built-in: it shadows the built-in everywhere (chat, and the workflows that follow it — see the Workflows section), and deleting it reverts. A built-in cannot be deleted, so \"delete\" **hides** it via `company/skills/.hidden.yaml`; hidden and shadowed built-ins are dropped from the index. `sync_builtin_skill_index` reconciles the built-in rows at startup, after a client-slot restore, and after a fixture reset — so a built-in added in a release reaches an already-seeded index, and a removed one leaves it.\n\n**Drafts.** The Executive's chat tools never change the library directly: `create_skill`, `update_skill` and `delete_skill` save a draft as JSON in `company/skills/.drafts/` (one per name; a newer proposal replaces the pending one). Drafts are not `*.md`, so they are never listed, indexed, searched, loaded or followed. A person approves a draft on the Playbooks tab (`POST /skill-drafts/{name}/approve`), which applies it through the ordinary skills operations, or discards it. Each save gets a fresh `id`, and approve/discard name the version the person saw: a proposal swapped in after review (say by a crafted inbound message) is never applied unseen, and approving never removes a newer draft that arrived meanwhile. This matches the draft → human-approval shape of custom workflows: a crafted inbound message can propose a playbook, but only a person can put one in effect.",+ "markdown": "Retrieval is handled by `openexecutive.knowledge.retriever.retrieve`, querying ChromaDB collections through `openexecutive.knowledge.store.ChromaDBStore`. When the caller passes `record_source`, `retrieve` also names every document its block quotes — company uploads by filename, built-in knowledge by a title made from its filename, Notion pages, synced Drive files by name with their Drive link, research notes by date, and earlier published documents with a link to `/artifacts/<id>` — so the web chat can list what an answer looked at: the chat route's own search, and each specialist's that answered (see the Lifecycle and API sections). The recording never raises, and a retrieval that fails leaves the specialist without context rather than failing the turn. Seven collections back the system:\n\n- **BUILTIN** — curated MBA-style domain knowledge shipped with the repo, including a `sales` domain (founder-led sales, qualification and pipeline, proposals and pricing conversations, follow-up and forecasting) and solo-founder guides in finance, marketing, legal and HR. Seeded at boot by `loader.seed_builtin_knowledge` (FAILURES by `seed_failures`): the whole tree on an empty collection, otherwise only the `SHIPPED_BUILTIN_FILES` entries with no chunks yet — so a doc added in a later release reaches an install seeded by an earlier one, instead of shipping, registering as approved, and never being retrievable. Presence is judged from each row's `source` path relative to `knowledge/builtin/` (not the absolute path, which moves with the install), read in one metadata scan narrowed to seeded rows so the external OER corpus sharing the collection is never pulled. A complete store indexes nothing.\n- **COMPANY** — customer documents ingested via the `/documents` endpoint. Curated uploads only — synced Notion pages and Drive files do not land here. A document's identity is its **filename**: chunk metadata and the chunk id both derive from it, so re-uploading upserts in place rather than duplicating, and `DELETE /documents/{filename}` matches the rows it claims to remove. Inbound attachments are **not** here — see ATTACHMENTS below; rows left by the earlier scheme are migrated out on boot. A scanned PDF (no text layer) is converted before chunking — see \"Reading scanned PDFs\" below — so it no longer indexes zero chunks while reporting `indexed`.\n- **NOTION_WIKI** — optional Notion sync (`NOTION_SYNC_ENABLED`) incrementally re-indexes pages shared with a Notion internal integration into a separate `notion_wiki` collection (`type=notion`). A Notion share is inherited and multi-writer, so this text is unreviewed relative to curated company docs; the retriever labels it as such and ranks it below COMPANY. Un-shared pages are purged on the next tick.\nSynced Drive files and Notion pages are listed on the knowledge page next to uploads (one Company documents list, each row badged with its source, its sync time and a link to the original), read from the sync state files rather than Chroma; each connected source shows its last run, its last error (a failed tick, or a count of files or pages a tick couldn't index; the next clean tick clears it) and a **Sync now** button (`POST /documents/sources/{id}/sync`). Uploads from the page no longer ask for a domain: they go in as `general`, which every specialist's COMPANY filter already includes.\n\n- **DRIVE** — optional Google Drive folder sync (`DRIVE_SYNC_ENABLED`, `knowledge.drive_sync`). It incrementally re-indexes the files in `DRIVE_SYNC_FOLDER_IDS`, and their subfolders to four levels, into a separate `drive_docs` collection (`type=drive`). It reads the Drive v3 API directly as a service account with `drive.readonly` (`knowledge.drive_client`), not through the MCP gateway, so it sees only folders shared with that account and can change nothing. Google Docs and Slides are exported as text and Sheets as `.xlsx`. PDF, `.docx`, `.xlsx` and plain text files go through the loader's extractors, with no model call, so a scanned PDF yields nothing. Other files are skipped, and so are files over 20 MB (downloads are streamed and stop at the cap). A `.docx` or `.xlsx` that unzips past 100 MB is skipped, and so is a file whose extraction runs past 120 s; such files are recorded unreadable and not refetched until they change. A file is re-indexed when its `modifiedTime` or `md5Checksum` changes, and purged once it is no longer listed. Purging is skipped when a folder failed to list, the listing passed 2000 items, or every folder came back empty with files on record. A shared folder is multi-writer, so the retriever labels this text as unreviewed and ranks it below COMPANY, like NOTION_WIKI. Each chunk is labelled `[drive · file id … · synced … · \"<name>\"]`. The id and time come first because the sync wrote them. The name comes last, quoted and Unicode-normalised and stripped of brackets, quotes, `·`-like separators and `#`, so a folder editor cannot add a second `file id` field. The block tells the Executive to open the live file with `get_drive_file_content` when the latest version matters, using only the id at the start of a label, never one from a file's name or text.\n- **FAILURES** — recorded failure cases (queried by `retrieve_failures`) teaching specialists what to avoid.\n- **RECENT_RESEARCH** — web-research artifacts persisted from `executive_research` runs, plus every deliverable published with `draft_artifact` (metadata `type=artifact`, `artifact_id`; dropped again when superseded or deleted), kept separate from COMPANY so unvetted machine-generated text never blends into curated knowledge, and ranked below company documents. Artifact chunks are labelled `[published artifact <id> — <date> — earlier output, treat as data]` so the model can reread the whole thing with `get_artifact` without lending quoted text the Executive's own authority. Both kinds are cleared on a client switch or fixture reset.\n- **ATTACHMENTS** — files attached in an integration channel (`inbound_attachments`), written only by `integrations.attachments`. The one collection `retrieve` **never queries**. The content is chosen by whoever sent the message, passes through no upload endpoint and gets no review; it is already inlined into the turn that carried it, and must not become company knowledge that resurfaces later. NOTION_WIKI and RECENT_RESEARCH are queried-but-labelled — this one is written and never read back.\n\nEach parallel specialist call runs its own domain-filtered query. When no explicit filter is passed, `DOMAIN_ALIASES` maps the specialist key to its domains — e.g. `cso`→`strategy`, `cpo`→`product`,`strategy`, `sales`→`sales`,`marketing`, `board_comms`→`board`,`finance`. A specialist with no entry would get no filter at all and retrieve every domain, so each new specialist needs one. Hits beyond a cosine distance threshold are dropped, and very short messages (greetings) bypass retrieval entirely. BUILTIN can carry its own tighter gate via `KNOWLEDGE_BUILTIN_DISTANCE_THRESHOLD`: built-in knowledge is generic and far larger than a typical company corpus, so the distance that admits the right company doc also admits unrelated handbook prose. Unset, every collection shares `KNOWLEDGE_DISTANCE_THRESHOLD`.\n\n`POST /documents` rejects any domain outside that set with a 400 — an unvalidated string would index the document under a domain no specialist filters on, failing silently and only at retrieval time. The tenth accepted value, `general`, is the catch-all for an upload nobody classified (it is the default on the endpoint, and what every upload from the knowledge page gets — the page no longer asks for a domain). It maps to no specialist, so every specialist's **company** filter is widened to include it — an unclassified document is visible to all rather than to none. That widening is deliberately not applied to BUILTIN, whose rows are shared with external OER sources that fall back to `general` when they declare no domains; fanning those into every specialist would blend unvetted third-party material into every answer.\n\nMulti-domain chunks fan out to one row per declared domain, so `_dedupe_by_text` drops duplicate-text hits while preserving relevance order before results are returned.\n\n### Embeddings\n\nEvery collection embeds with one shared all-MiniLM-L6-v2 ONNX session (`knowledge.store._embedding_function`), the same model and vectors as Chroma's default. Chroma's own default reloads the model on every call and keeps ONNX Runtime's memory arena, so a 300-chunk upload peaked near 760 MB and each query spent ~240 ms reloading. The shared session is built once, runs without the arena and embeds four texts at a time (the model pads every text to 256 tokens, so batch size sets the peak): ~300 MB and ~30 ms. It answers to Chroma's name `default` with an empty config, because every existing collection records that name and Chroma refuses a collection opened with a differently named function; and it must not be a `DefaultEmbeddingFunction` instance, which Chroma swaps for a fresh default on every embed.\n\n### Reading scanned PDFs\n\npypdf returns only a PDF's saved text layer, so a scan, a phone photo saved as PDF, or a deck printed to PDF as images used to come back empty everywhere a PDF is read. `knowledge.pdf_reader.read_pdf_text` tries three readers in order and never raises:\n\n1. **Text layer** (pypdf) — used whenever it yields real text (at least ~20 visible characters per page, so a scan carrying only page numbers still falls through).\n2. **The deployment's own model, through its provider's PDF support** — opt-in, `PDF_PROVIDER_READING=true` (off by default: an upgrade never starts sending scanned PDFs off the server; this also means an Anthropic-direct deployment OCRs scans locally until it opts in) — the pages as a base64 `document` block, transcribed to Markdown by `PDF_VISION_MODEL` (unset: `DEFAULT_MODEL`, the model the deployment already runs on), `PDF_VISION_PAGES_PER_CALL` pages per request (default 20), three requests at a time. Each provider carries the block its own way: Anthropic reads it natively; on OpenRouter the translator makes it an OpenAI `file` part and the provider adds the `file-parser` plugin — engine `native` for Claude or any model the catalog lists with `file` input (OpenAI's GPT-4o and later, Gemini…), else `PDF_OPENROUTER_ENGINE` (default `mistral-ocr`, $2 per 1,000 pages); a local OpenAI-compatible server gets the `file` part only with `LOCAL_PDF_INPUT=true` (e.g. `LOCAL_BASE_URL` pointed at OpenAI's own API). `providers.registry.pdf_input_supported` decides; a model that cannot take one never receives it (the feature gate swaps a stray `document` block for a note). Turning it on sends scanned pages off the server — to the provider, and on OpenRouter possibly to its parser (Mistral OCR) — and the destination is logged once per process.\n3. **Local OCR** — pages rendered with pypdfium2 and read by RapidOCR (ONNX, models bundled in the wheel): offline, no key, no per-page cost. The default reader while step 2 is off, what a local model without PDF input gets, and the fallback on every provider when step 2 errors, refuses or returns nothing. `PDF_OCR_ENABLED=false` turns it off.\n\n`PDF_VISION_MAX_PAGES` (default 100) caps the pages read, with a note saying how many were; a file a channel delivered (`inbound=True`) is capped at `PDF_INBOUND_MAX_PAGES` (30) and metered by a rolling `PDF_INBOUND_PAGES_PER_HOUR` (300) budget. OCR is bounded too: a page renders within a 25-megapixel budget whatever its MediaBox claims (a crafted 20000pt page would otherwise allocate gigabytes), at most two documents OCR at once, and each stops after 240 s with what it has. A PDF of more than 2,000 pages is refused before any page is parsed (the caps above bound conversion, not the text-layer pass). A Claude slice that runs into the output limit is split in half until each part fits; a single page that still does not fit keeps what was written, marked `[transcription cut off here]`, and the note says so. A result is cached in process by the file's sha256 (32 entries) so a re-read does not re-bill; a failure is not cached. `loader.read_document_text` / `extract_text_from_file_async` route a PDF through it and every other type through the sync extractor, and are what `ingest_file` (uploads, boot reconcile), the `/documents/{filename}` preview, intake uploads, chat attachments, the email poller, `oe__read_file` and the Executive's `read_document` tool use.\n\n### Parsing in a child process\n\nParsing a large document builds hundreds of MB of small Python objects, and CPython keeps the memory they lived in, so a parse inside the API process left its peak there for good. On a 34 MB, 131-page text-layer PDF uploaded through `POST /documents`, uvicorn went from 272 MB to a 440 MB peak and stayed at 378 MB. On a 30-page scan read by OCR it peaked at 787 MB and stayed at 446 MB. Now the text-layer pass and local OCR in `pdf_reader`, and the PDF, Word and Excel extractors behind `loader.extract_text_from_file`, run in a short-lived child process (`knowledge.isolated.run_isolated`). Everything the child allocated goes back to the OS when it exits. The same uploads now peak at 324 MB and 297 MB and settle at 318 MB and 290 MB, and what remains is embedding. The OCR child itself still peaks near 600 MB while it reads, then exits.\n\nThe call goes to the child pickled on stdin and the answer comes back as JSON, so the API never unpickles anything a hostile file could shape. Both of the child's output streams go to temp files, not the API's memory. The child logs nothing, because pypdf logs text taken from the file and a crafted 9 KB PDF made it write megabytes. Only the last 2,000 characters of its stderr are read back, and an answer over 32 MB is refused. The child inherits only what it needs to start Python (`PATH`, `HOME`, `PYTHONPATH`, the library path, locale, temp dir), not the deployment's keys. That is hygiene rather than a sandbox, since the child runs as the same user. A PDF read by path is cached only if its hash is unchanged after the read, so an upload that replaces the file mid-read cannot store its text under the old file's hash. `read_document_text` hands `pdf_reader` the file's path, so the API process holds a whole PDF only when its pages go to the model (step 2). The contract is unchanged. `read_pdf_text` still never raises: a child that dies or runs past its limit (300 s for the text layer, or OCR's 240 s budget plus 120 s) comes back as `method=\"none\"` with a note. A Word or Excel parse error still raises, as `IsolatedError` naming the original. At most two parser processes run at once. A caller waits at most 30 seconds for a free slot, and that wait counts against its own time limit. If no slot frees up in time, the file is reported as \"busy, try again\" rather than unreadable. An upload, PDF or not, gets a 503 and nothing is stored. Drive sync retries the file on its next tick. A PDF read elsewhere comes back empty with a note saying so, and is not cached. OCR has its own two-slot limit, so a long OCR never holds up a quick text-layer parse. A scan waits up to one OCR run (240 s) for a slot, and if none frees up it gives its pages back to the hourly inbound budget. Only when there is no usable Python to start does the parse run in-process as before, and it does not take a slot. Failing to start a process for lack of memory is reported as unreadable, because that is the worst moment to parse inside the API. A Word or Excel file that cannot be read is a 422 from `POST /documents` and the preview, not a 500. An Excel workbook is read for at most 200,000 rows (blank ones included) and 1,024 columns: openpyxl walks every row a sheet's `<dimension>` claims, so a few-KB file claiming A1:XFD1048576 would otherwise hold a parser slot until the timeout. `POST /documents` accepts `.pdf`, `.docx`, `.doc`, `.xlsx`, `.xlsm`, `.csv`, `.md` and `.txt`; text formats are decoded as UTF-8 with bad bytes replaced.\n\n`POST /documents` streams the upload to its staging file 1 MB at a time and returns 413 as soon as it passes 50 MB, instead of reading the whole body into memory first. The stored copy is copied from that file.\n\n### The SME review gate\n\nBefore the distance threshold applies, both `retrieve` and `retrieve_failures` drop **withheld** items — anything the review store reports as `pending` or `rejected` (`ReviewStore.get_withheld_filenames`). Approved items with a priority set are then sorted ahead of the rest.\n\nKnowledge shipped with the product registers as a trusted default (`approved`, NULL `reviewed_at`), so nothing is withheld until a human deliberately queues a domain for curation or rejects something. See the **SME Knowledge Review** section for the full state model. The filter matches on the `(domain, filename)` pair Chroma carries. A bare filename was ambiguous *and* caller-choosable — `POST /knowledge/builtin` takes any `(domain, filename)`, so uploading a file named after a shipped doc in another domain silently withheld that shipped doc from every specialist. Failure case studies are keyed in their own namespace, so a user-authored one cannot collide with a shipped one.\n\nThe formatted context is injected into the **user turn** (wrapped in `<relevant_knowledge>` by `BaseAgent.analyze`), never into a cached system block — per-query hits would otherwise poison the prompt cache.\n\n### Skills (Playbooks) collection\n\nSkills — called **playbooks** in the UI, where they are a tab on Workflows — are Markdown procedures with YAML frontmatter, indexed one document per skill in their own `skills` collection (name + description + when_to_use; the body is fetched by `load_skill`). Built-ins ship under `knowledge/builtin/skills/`; company skills live in `company/skills/`. Customizing a built-in (a `PUT` from the Playbooks tab; the chat tools refuse built-ins) writes a company skill of the same name flagged `customizes_builtin: true`, which **replaces** the built-in: it shadows the built-in everywhere (chat, and the workflows that follow it — see the Workflows section), and deleting it reverts. A built-in cannot be deleted, so \"delete\" **hides** it via `company/skills/.hidden.yaml`; hidden and shadowed built-ins are dropped from the index. `sync_builtin_skill_index` reconciles the built-in rows at startup, after a client-slot restore, and after a fixture reset — so a built-in added in a release reaches an already-seeded index, and a removed one leaves it.\n\n**Drafts.** The Executive's chat tools never change the library directly: `create_skill`, `update_skill` and `delete_skill` save a draft as JSON in `company/skills/.drafts/` (one per name; a newer proposal replaces the pending one). Drafts are not `*.md`, so they are never listed, indexed, searched, loaded or followed. A person approves a draft on the Playbooks tab (`POST /skill-drafts/{name}/approve`), which applies it through the ordinary skills operations, or discards it. Each save gets a fresh `id`, and approve/discard name the version the person saw: a proposal swapped in after review (say by a crafted inbound message) is never applied unseen, and approving never removes a newer draft that arrived meanwhile. This matches the draft → human-approval shape of custom workflows: a crafted inbound message can propose a playbook, but only a person can put one in effect.","mermaid": "flowchart TD\n Call[\"Specialist call<br/>(domain-filtered)\"] --> Q[\"retrieve(query, domain)\"]\n Q --> Builtin[(BUILTIN)]\n Q --> Company[(COMPANY)]\n Q --> NotionWiki[(NOTION_WIKI)]\n Q --> DriveDocs[(DRIVE)]\n Q --> Failures[(FAILURES)]\n Q --> Research[(RECENT_RESEARCH)]\n Attach[\"integrations.attachments\"] --> Attachments[(ATTACHMENTS<br/>never queried)]\n Builtin --> Dedupe[\"dedupe by text<br/>+ distance gate\"]\n Company --> Dedupe\n NotionWiki --> Dedupe\n DriveDocs --> Dedupe\n Failures --> Dedupe\n Research --> Dedupe\n Dedupe --> Inject[\"Inject into USER turn<br/>(not cached)\"]\n class Call entry\n class Q compute\n class Dedupe compute\n class Builtin storage\n class Company storage\n class NotionWiki storage\n class DriveDocs storage\n class Failures storage\n class Research storage\n class Attachments storage\n class Attach compute\n class Inject hot",- "generated_at": "2026-10-01T15:27:37.505516+00:00"+ "generated_at": "2026-10-01T18:22:10.000000+00:00"}diff --git a/packages/core/openexecutive/knowledge/loader.py b/packages/core/openexecutive/knowledge/loader.pyindex 853a5563..b83db31f 100644--- a/packages/core/openexecutive/knowledge/loader.py+++ b/packages/core/openexecutive/knowledge/loader.py@@ -69,6 +69,13 @@ _LEGACY_ATTACHMENT_DOMAIN = "company_docs"_ISOLATED_SUFFIXES = frozenset({".pdf", ".docx", ".doc", ".xlsx", ".xlsm"})_PARSE_TIMEOUT_S = 300.0+# openpyxl's read-only reader takes a sheet's size from its ``<dimension>``+# element and yields a filler row for every row the file leaves out, so a+# few-KB workbook claiming A1:XFD1048576 means a billion empty cells to walk.+# Rows (blank ones included) and columns read per workbook are capped.+_XLSX_MAX_ROWS = 200_000+_XLSX_MAX_COLS = 1_024+def chunk_text(text: str, chunk_size: int = 512, overlap: int = 50) -> list[str]:words = text.split()@@ -113,18 +120,29 @@ def extract_text_from_xlsx(path: Path, max_chars: int = 200_000) -> str:stored cell values (``data_only=True`` returns cached formula results, notformulae); legacy binary ``.xls`` is not supported by openpyxl.- ``read_only`` streams rows and ``max_chars`` bounds the accumulated text, so- a decompression-bombed workbook (a small archive that inflates to millions- of cells) can't exhaust memory."""+ ``read_only`` streams rows and ``max_chars`` bounds the accumulated text.+ At most ``_XLSX_MAX_ROWS`` rows, blank or not (each sheet counts as+ one more), are read across the workbook, and ``_XLSX_MAX_COLS`` columns of each, so a sheet that only+ claims a huge size can't keep the parser busy. Shared strings and styles+ are still read whole by openpyxl before any row."""from openpyxl import load_workbookwb = load_workbook(filename=str(path), read_only=True, data_only=True)try:parts: list[str] = []total = 0+ rows_left = _XLSX_MAX_ROWSfor ws in wb.worksheets:+ # Each sheet costs a row too, so thousands of empty sheets can't+ # get past the budget.+ rows_left -= 1+ if rows_left < 0:+ return "\n".join(parts)heading_written = False- for row in ws.iter_rows(values_only=True):+ for row in ws.iter_rows(max_col=_XLSX_MAX_COLS, values_only=True):+ rows_left -= 1+ if rows_left < 0:+ return "\n".join(parts)cells = [str(c) for c in row if c is not None]if not cells:continue@@ -169,7 +187,9 @@ def _parse_file(path: Path) -> str:elif suffix in (".xlsx", ".xlsm"):return extract_text_from_xlsx(path)elif suffix in (".md", ".txt", ".rst", ".csv"):- return path.read_text(encoding="utf-8")+ # Lenient: a CSV saved by Excel is often cp1252, and a strict decode+ # error would surface as a 500 rather than a readable document.+ return path.read_text(encoding="utf-8", errors="replace")return ""diff --git a/packages/core/tests/unit/test_documents_upload.py b/packages/core/tests/unit/test_documents_upload.pyindex 2da55f1a..b3654a03 100644--- a/packages/core/tests/unit/test_documents_upload.py+++ b/packages/core/tests/unit/test_documents_upload.py@@ -112,6 +112,55 @@ def test_scanned_pdf_upload_is_indexed_and_previewed(assert "rent 12,000 per month" in preview.json()["content"][email protected]("name", ["budget.xlsx", "budget.xlsm"])+def test_an_excel_upload_is_indexed_and_previewed(client: TestClient, name: str) -> None:+ """(#316) Excel workbooks were refused as an unsupported type even though+ the loader reads them."""+ from openpyxl import Workbook++ wb = Workbook()+ ws = wb.active+ ws.title = "Budget"+ ws.append(["Line", "Amount"])+ ws.append(["Marketing", 45000])+ buf = io.BytesIO()+ wb.save(buf)+ buf.seek(0)+ files = {"file": (name, buf, "application/octet-stream")}++ resp = client.post("/documents", files=files, data={"domain": "finance"})++ assert resp.status_code == 200, resp.text+ assert resp.json()["chunks_indexed"] >= 1+ store: _CapturingStore = client.app.state.store # type: ignore[attr-defined]+ assert any(m["filename"] == name for m in store.rows.values())++ preview = client.get(f"/documents/{name}")+ assert preview.status_code == 200, preview.text+ assert "Marketing\t45000" in preview.json()["content"]+++def test_a_csv_upload_is_indexed(client: TestClient) -> None:+ files = {"file": ("pipeline.csv", io.BytesIO(b"deal,value\nAcme,120000\n"), "text/csv")}++ resp = client.post("/documents", files=files)++ assert resp.status_code == 200, resp.text+ assert resp.json()["chunks_indexed"] >= 1+++def test_an_unsupported_type_lists_the_allowed_ones_in_order(client: TestClient) -> None:+ files = {"file": ("old.xls", io.BytesIO(b"\xd0\xcf\x11\xe0"), "application/vnd.ms-excel")}++ resp = client.post("/documents", files=files)++ assert resp.status_code == 400+ assert resp.json()["detail"] == (+ "Unsupported file type: .xls. "+ "Allowed: .csv, .doc, .docx, .md, .pdf, .txt, .xlsm, .xlsx"+ )++def test_get_document_missing_returns_404(client: TestClient) -> None:resp = client.get("/documents/does_not_exist.md")assert resp.status_code == 404diff --git a/packages/core/tests/unit/test_loader_extract.py b/packages/core/tests/unit/test_loader_extract.pyindex 61778014..5db9f4a6 100644--- a/packages/core/tests/unit/test_loader_extract.py+++ b/packages/core/tests/unit/test_loader_extract.py@@ -7,6 +7,8 @@ from __future__ import annotationsfrom pathlib import Path+import pytest+from openexecutive.knowledge.loader import (extract_text_from_file,extract_text_from_xlsx,@@ -53,6 +55,73 @@ def test_extract_text_from_xlsx_respects_char_cap(tmp_path: Path) -> None:assert len(capped) < 1000 # stopped well before flattening all 100 rows+def test_a_sheet_that_only_claims_a_huge_size_is_read_quickly(tmp_path: Path) -> None:+ """(#316) Two cells at A1 and XFD1048576 make a ~5 KB file that openpyxl+ walks as a billion empty cells. The row and column caps stop it."""+ import time++ from openpyxl import Workbook++ wb = Workbook()+ ws = wb.active+ ws["A1"] = "kept"+ ws["XFD1048576"] = "out of range"+ path = tmp_path / "sparse.xlsx"+ wb.save(str(path))+ assert path.stat().st_size < 20_000++ start = time.monotonic()+ text = extract_text_from_xlsx(path)+ assert time.monotonic() - start < 20+ assert "kept" in text+ assert "out of range" not in text+++def test_blank_rows_count_toward_the_xlsx_row_cap(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from openpyxl import Workbook++ from openexecutive.knowledge import loader++ monkeypatch.setattr(loader, "_XLSX_MAX_ROWS", 10)+ wb = Workbook()+ ws = wb.active+ ws["A1"] = "first"+ ws["A50"] = "past the cap"+ path = tmp_path / "gaps.xlsx"+ wb.save(str(path))++ text = extract_text_from_xlsx(path)+ assert "first" in text+ assert "past the cap" not in text+++def test_empty_sheets_count_toward_the_xlsx_row_cap(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from openpyxl import Workbook++ from openexecutive.knowledge import loader++ monkeypatch.setattr(loader, "_XLSX_MAX_ROWS", 5)+ wb = Workbook()+ for i in range(10):+ wb.create_sheet(f"Empty{i}")+ wb.create_sheet("Last")["A1"] = "past the cap"+ path = tmp_path / "sheets.xlsx"+ wb.save(str(path))++ assert "past the cap" not in extract_text_from_xlsx(path)+++def test_a_non_utf8_csv_is_read_not_raised(tmp_path: Path) -> None:+ path = tmp_path / "excel-export.csv"+ path.write_bytes("client,fee\nCafé Noir,1200\n".encode("cp1252"))+ text = extract_text_from_file(path)+ assert "Noir,1200" in text++def test_extract_text_from_csv(tmp_path: Path) -> None:path = tmp_path / "roster.csv"path.write_text("name,role\nDana Reyes,CEO\n", encoding="utf-8")diff --git a/packages/ui/src/components/knowledge/CompanyPanel.tsx b/packages/ui/src/components/knowledge/CompanyPanel.tsxindex ff3e3978..0e3de0d9 100644--- a/packages/ui/src/components/knowledge/CompanyPanel.tsx+++ b/packages/ui/src/components/knowledge/CompanyPanel.tsx@@ -42,7 +42,7 @@ interface Viewing {content: string;}-const ACCEPT = ".pdf,.docx,.doc,.md,.txt";+const ACCEPT = ".pdf,.docx,.doc,.xlsx,.xlsm,.csv,.md,.txt";const POLL_MS = 3000;const PROSE_CLASS =@@ -273,7 +273,7 @@ export default function CompanyPanel({ onCountChange }: CompanyPanelProps) {? "No documents yet. Drop files here to add your first ones.": "Drop files here to add them"}<span className="block text-xs text-fg-subtle mt-1">- PDF, Word, Markdown or text, up to 50 MB each+ PDF, Word, Excel, CSV, Markdown or text, up to 50 MB each</span></p>)}