Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ It began as an exploratory PDF-chat prototype. It now includes a product landing

## One conversation for the job

The product page opens with a full-screen gradient hero, followed by a concise “How it works” section and a crisp HTML/CSS preview. Team credits and deeper technical details live in the docs. **Open Mantis** opens the working chat: upload a manual, ask a question, attach a photo, and expand sources beneath the answer. **Try an example** opens that same interface with a sample conversation. Manuals live in a small drawer; there is no separate demo interface or library page.
The product page opens with a full-screen black hero with a gradient headline, followed by a concise “How it works” section and interactive examples rendered in HTML/CSS. Team credits and deeper technical details live in the docs. **Open Mantis** opens the working chat: upload a manual, ask a question, attach a photo, and expand sources beneath the answer. **Try an example** on the landing page scrolls to local examples; their source notes expand inline, and previous exchanges remain in the scrolling transcript. The full app also offers sample conversations in its own chat. The top manual picker lists uploaded documents. The left **Your chats** drawer lists saved conversations so you can reopen them; there is no separate library page.

![Mantis product page](docs/assets/product.jpg)

![Mantis chat with a connected context, inline sources, and manual upload](docs/assets/workspace.jpg)
![Mantis saved conversations in the Your chats drawer](docs/assets/workspace.jpg)

## What you can do

Expand Down Expand Up @@ -65,7 +65,7 @@ Open the **[product page](http://127.0.0.1:8000)** or go directly to the **[work

### 1. Try the same app with an example

Choose **Try an example**, or open [`/workspace#demo`](http://127.0.0.1:8000/workspace#demo). The chat starts with a scripted spindle-overload scenario. Try the illustrative alarm-screen attachment, ask a maintenance handover question, and expand the sample source. No API key or AI calls are involved. Personal photos attached in example mode stay in the browser and are not analyzed.
Use the landing page’s sample questions and expandable notes without leaving the page. To explore examples in the full chat, choose **Try an example** there, or open [`/workspace#demo`](http://127.0.0.1:8000/workspace#demo). The chat starts with a scripted spindle-overload scenario. The landing page offers suggested questions for vibration, overheating, alarm photos, and maintenance records in one scrollable chat; each click appends another exchange. Try the illustrative alarm-screen attachment, ask a maintenance handover question, and expand the sample source. No API key or AI calls are involved. Personal photos attached in example mode stay in the browser and are not analyzed.

Choose **Exit example** or upload your own manual to leave example mode. Then attach a photo or ask about the selected manual to use the real backend. Switching modes resets the conversation, so example replies never enter a live request's history.

Expand All @@ -81,7 +81,7 @@ In live mode, attach one JPEG, PNG, or WebP photo (up to 8 MB and 20 megapixels)

Live image handling follows the [official OpenAI image-input format](https://developers.openai.com/api/docs/guides/images-vision). The configured chat model must support image input and strict structured outputs. This request path has been tested with a fake provider; live image accuracy and provider compatibility still need validation with a valid key.

Mantis does not persist photos or conversations. The browser sends the last four successful text exchanges as follow-up context; old image bytes are not resent. Reattach a photo when it needs to be examined again. The provider's data-processing policies apply to live requests.
Mantis saves conversation text and cited passages in the workspace’s local server database. Photo files are not saved; reopened chats show a note where a personal photo was attached. The browser sends the last four successful text exchanges as follow-up context; old image bytes are not resent. Reattach a photo when it needs to be examined again. The provider's data-processing policies apply to live requests.

### 4. Verify the source

Expand All @@ -97,8 +97,8 @@ Read the [architecture guide](docs/architecture.md) for retrieval behavior, conc

## Quality and current limits

- **34 Python regression tests** cover real PDF extraction with a fake provider, storage isolation, persistence, deletion, concurrency, request limits, and citation handling.
- **12 frontend regressions** cover bounded follow-up context, stale responses and reset cancellation, retry handling, mode/manual resets, current-message-only photos, and key-free examples.
- **48 Python regression tests** cover real PDF extraction with a fake provider, storage isolation, persistence, deletion, concurrency, request limits, and citation handling.
- **20 frontend regressions** cover bounded follow-up context, stale responses and reset cancellation, retry handling, mode/manual resets, current-message-only photos, and key-free examples.
- **CI** runs Python/frontend tests and lint/format checks, JavaScript syntax/format checks, and an independent built-wheel smoke test for pages, assets, and the demo API.
- **Browser checks** cover desktop/mobile layouts, demo citations, keyboard focus, and cancelling/reselecting a file.
- **Still to evaluate:** representative industrial answer quality and live-provider behavior. Software tests are not evidence of troubleshooting accuracy.
Expand Down
2 changes: 1 addition & 1 deletion docs/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The engineer remains responsible for checking the actual manual and following ap
- Text-based PDF upload, indexing, and a persistent manual library.
- Questions scoped to one equipment manual, with a retrieval cutoff for weak matches.
- Answers with validated source identifiers, page numbers, and inspectable excerpts.
- Browser-scoped workspaces, duplicate detection, and document/index deletion.
- Browser-scoped workspaces, duplicate detection, document/index deletion, and saved text conversations with restore/delete actions.
- One chat for manual questions, photos, follow-ups, and inline sources. A key-free example runs in that same interface with scripted replies; personal example photos stay local.

The application is a local pilot. Software regression tests cover its API and storage behavior; retrieval quality and answer correctness have not yet been evaluated on a representative set of industrial manuals.
Expand Down
8 changes: 7 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ curl --cookie data/dev.cookies \

Real questions use `demo: false` and the selected manual's `document_id`, returned by the upload/list endpoints. Optional `history` contains up to eight text turns (`role`: `user` or `assistant`, `content`: up to 10,000 characters). The browser sends the last four successful exchanges and resets them when the manual or mode changes. History is context, not evidence. Responses contain `answer`, `sources`, `insufficient_evidence`, and `demo`. A source contains its document identifier, name, page, and text.

Optional `image` is a base64 data URL for one valid JPEG, PNG, or WebP image up to 8 MB / 20 megapixels; animated images and remote URLs are rejected. Question request bodies are limited to 12 MB before JSON parsing. The image is sent to the provider for visible observations/transcription, which inform manual retrieval. Without a manual, an image (or follow-up history) can request observations/context collection, with `insufficient_evidence: true` and no citations. Old images are not part of text history. Photos and chat turns are not stored by Mantis. The legacy `demo: true` API still returns training-manual excerpts and rejects attached images; the app’s example conversation runs locally in the same chat UI.
Optional `image` is a base64 data URL for one valid JPEG, PNG, or WebP image up to 8 MB / 20 megapixels; animated images and remote URLs are rejected. Question request bodies are limited to 12 MB before JSON parsing. The image is sent to the provider for visible observations/transcription, which inform manual retrieval. Without a manual, an image (or follow-up history) can request observations/context collection, with `insufficient_evidence: true` and no citations. Old images are not part of text history. Photo files are not stored by Mantis; completed text exchanges and sources can be saved through the chat-history endpoints. The legacy `demo: true` API still returns training-manual excerpts and rejects attached images; the app’s example conversation runs locally in the same chat UI.

For real PDF uploads, configure the provider first. Uploaded text is sent for embedding, and retrieved passages/questions, recent text history, and photo observations are sent for answer generation. Duplicate detection can reuse an existing document; a new upload can incur provider usage.

Expand All @@ -63,3 +63,9 @@ For real PDF uploads, configure the provider first. Uploaded text is sent for em
| 503 | Real PDF analysis requested without a configured API key |

Some failures return JSON `detail`; Host validation can return plain text. Source-ID validation checks identifiers against retrieved passages and is not a claim-level correctness guarantee.

## Saved chats

`GET /api/chats` lists this workspace’s chat metadata; `GET /api/chats/{id}` returns its transcript. `POST /api/chats` creates a chat; `PUT /api/chats/{id}` updates it with the last returned `revision`; stale revisions or attempts to change manual/mode return 409. `DELETE /api/chats/{id}` removes the owned chat. Unknown/other-workspace chats return 404.

Save payloads contain `document_id`, `demo`, `revision`, and `messages`. Messages must be completed alternating user/assistant pairs, each with `role`, `content`, optional source records, `demo`, `insufficient_evidence`, and `photo` (`""`, `"sample"`, or `"omitted"`). Extra fields, personal photo data, privileged roles, and oversized transcripts are rejected. Limits: 100 messages per chat, 100 chats per workspace, 1 MB per save. Deleting a manual does not delete saved conversations.
8 changes: 6 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Each question specifies one manual. Retrieval embeds the question using that man

The model returns a structured answer and source identifiers. The API checks that identifiers refer to retrieved passages and that a substantive answer has sources. These checks establish source identity; they do not prove that every answer claim is supported. The threshold and answer behavior need evaluation against representative manuals and questions.

The frontend supplies up to eight successful text turns for follow-up context. Retrieval includes the last two user questions and current photo observations. History and image text are treated as untrusted context, never as verified manual evidence. New chat, manual changes, and live/example transitions reset history. Photos are validated (format, bytes, pixels, animation), transcribed/described by the configured image-capable model, and used to inform retrieval. Without relevant excerpts, photos can support observations and clarification but cannot produce a source-backed diagnosis. No photos or chat turns are persisted by Mantis.
The frontend supplies up to eight successful text turns for follow-up context. Retrieval includes the last two user questions and current photo observations. History and image text are treated as untrusted context, never as verified manual evidence. New chat, manual changes, and live/example transitions reset history. Photos are validated (format, bytes, pixels, animation), transcribed/described by the configured image-capable model, and used to inform retrieval. Without relevant excerpts, photos can support observations and clarification but cannot produce a source-backed diagnosis. Conversation text and cited passages are stored in workspace-scoped SQLite chats after successful exchanges; photo bytes are not stored. Reopening a chat restores its manual/mode and last four text exchanges. Revision checks reject stale updates from another tab. Chats have a 1 MB request limit, 100-message cap, and 100-chat workspace quota. A removed manual leaves its chat readable but blocks continuation under that missing context.

## Workspace boundary

Expand All @@ -44,8 +44,12 @@ The current limits are 30 manuals per workspace and 2,000 chunks per manual. Bru

## Product and frontend layout

`/` serves the product presentation; `/workspace` serves the working assistant. Both pages are packaged under `mantis/web/pages/` and use self-hosted assets. CSS lives in `mantis/web/css/`; JavaScript modules live in `mantis/web/js/`. The product page is a static presentation with a real screenshot and links into one working chat app. `/workspace#demo` loads a scripted example into that same app. `conversation.js` owns cancellation and bounded text history; `examples.js` contains the key-free scenarios; `workspace.js` binds uploads, photos, the manual drawer, and inline expandable sources. There is no parallel demo interface or full library page.
`/` serves the product presentation; `/workspace` serves the working assistant. Both pages are packaged under `mantis/web/pages/` and use self-hosted assets. CSS lives in `mantis/web/css/`; JavaScript modules live in `mantis/web/js/`. The product page is a presentation with inline scripted examples and links into one working chat app. `product-preview.js` reuses `examples.js` for the landing examples; source details expand locally without navigation. `/workspace#demo` loads a scripted example into that same app. `conversation.js` owns cancellation and bounded text history; `examples.js` contains the key-free scenarios; `workspace.js` binds uploads, photos, the manual drawer, and inline expandable sources. There is no parallel demo interface or full library page.

The landing page follows the owner-supplied design reference while using the original presentation's logos, team portraits, names, and role labels. Mock telemetry, inventory records, invented performance figures, and unsupported certifications from the reference are not product data.

The Python wheel includes HTML, CSS, scripts, fonts, logos, and portraits through setuptools package data. Runtime data and `.env` are resolved from the working directory, so an installed package can run outside the source checkout.

## Frontend revisions

`mantis/frontend.py` fingerprints the CSS/JavaScript bundle and places page assets under a shared `/static/v/{revision}/` URL prefix. Relative module and stylesheet imports inherit that prefix, so new HTML does not reuse an older cached module graph. HTML and static responses use `Cache-Control: no-cache` for revalidation; API responses remain `no-store`. The existing `/static/` paths remain supported, and Starlette still enforces the public-directory boundary. Font URLs are relative to the stylesheet.
2 changes: 1 addition & 1 deletion docs/assets/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
- `banner.svg`: editable artwork for the GitHub README, using the existing Mantis mark and black/orange project identity.
- `banner.png`: 1280 × 400 raster export, so GitHub renders the bundled Anton and Space Mono typography consistently.
- `product.jpg`: screenshot of the real product landing page.
- `workspace.jpg`: screenshot of the actual unified chat in example mode, with no private manuals or credentials.
- `workspace.jpg`: screenshot of the actual Your chats drawer with a saved example conversation and no private manuals or credentials.

The banner source embeds the original Mantis mark. The PNG was rendered from that SVG with resvg using `mantis/web/assets/Anton-Regular.ttf` and `mantis/web/assets/SpaceMono-Regular.ttf`. Font licenses and brand provenance are documented in [the application asset guide](../../mantis/web/assets/README.md).
Binary file modified docs/assets/product.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/workspace.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ For a new setup, copy `.env.example` to `.env` and configure the key locally. `.

The default server limits are 20 MB and 300 pages per PDF, 2,000 chunks per manual, and 30 manuals per workspace. The multipart-body limiter allows a bounded envelope in addition to the file limit.

Uploaded manual text is sent to OpenAI to create embeddings. Questions, the last four successful text exchanges, and retrieved excerpts are sent for answer generation. In live mode, a current-message photo is sent for visual observations, which can inform manual retrieval; photos are limited to JPEG/PNG/WebP, 8 MB and 20 megapixels. Photos and chat history are not persisted by Mantis. The question-body cap is 12 MB. The original PDF remains in the local database. Example mode uses the same chat interface with scripted replies, makes no AI calls, and keeps attached photos local. Live photos follow the [official OpenAI image-input format](https://developers.openai.com/api/docs/guides/images-vision); configured key/model availability still needs a live-provider check.
Uploaded manual text is sent to OpenAI to create embeddings. Questions, the last four successful text exchanges, and retrieved excerpts are sent for answer generation. In live mode, a current-message photo is sent for visual observations, which can inform manual retrieval; photos are limited to JPEG/PNG/WebP, 8 MB and 20 megapixels. Chat text and sources are saved in the local SQLite database under the same browser-workspace cookie as manuals. Photo files are not persisted. Chat history is limited to 100 chats per workspace, 100 messages per chat, and 1 MB per save request. The question-body cap is 12 MB. The original PDF remains in the local database. Example mode uses the same chat interface with scripted replies, makes no AI calls, and keeps attached photos local. Live photos follow the [official OpenAI image-input format](https://developers.openai.com/api/docs/guides/images-vision); configured key/model availability still needs a live-provider check.

Changing the embedding model affects new indexes. Existing manuals retain their model identifier for compatible question embeddings. A model identifier still needs to be available to the configured provider account.

Expand Down
2 changes: 2 additions & 0 deletions docs/running.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,5 @@ After changing `.env`, restart the server. `--reload` watches source changes; do
| Cookie does not persist over local HTTP | Use `MANTIS_SECURE_COOKIE=false` locally. Secure cookies require HTTPS. |

See [configuration](configuration.md), [API usage](api.md), and [deployment boundaries](deployment.md).

If an older checkout renders with overlapping controls or default browser buttons, perform one hard reload (Chrome on macOS: Command–Shift–R). Current releases use revisioned CSS/script URLs and revalidation headers so normal reloads pick up interface changes together.
Loading
Loading