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
39 changes: 25 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,15 @@

**Mantis helps maintenance engineers find answers in equipment manuals and trace them back to the source.** Upload a PDF, select the right equipment manual, and ask about a symptom, fault code, or maintenance procedure. Inspect the supporting passages and open the original PDF at the cited page.

It began as an exploratory PDF-chat prototype. It now includes a product landing page, a dedicated maintenance workspace, a persistent manual library, browser-scoped workspaces, single-pass indexing, validated citation identifiers, and an offline demo. Speech and object-detection notebooks remain research work.
It began as an exploratory PDF-chat prototype. It now includes a product landing page, a single chat app, a persistent manual library, browser-scoped workspaces, single-pass indexing, validated citation identifiers, and an offline demo. Speech and object-detection notebooks remain research work.

## Product and workspace
## One conversation for the job

The product page introduces Mantis and includes a live, illustrative demo. The dedicated workspace handles your manuals, questions, and source inspection.
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.

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

![Mantis maintenance workspace with its equipment-manual selector, troubleshooting assistant, and source inspector](docs/assets/workspace.png)
![Mantis chat with a connected context, inline sources, and manual upload](docs/assets/workspace.jpg)

## What you can do

Expand All @@ -40,9 +40,9 @@ The product page introduces Mantis and includes a live, illustrative demo. The d
| **Ask the right source** | Scope each question to one selected manual so equipment documentation stays separate. |
| **Inspect an answer** | See cited excerpts, page numbers, and the original PDF at the referenced page. |
| **Manage your workspace** | Reuse duplicate files, delete individual manuals, or clear documents and their indexes. |
| **Try it without a key** | Explore a clearly labeled training scenario with illustrative source excerpts and no AI calls. |
| **Try it without a key** | Try a scripted CNC conversation, a prepared alarm-screen example, and local photo previews with no AI calls. |

The current app is a **local pilot**. It does not operate machines or certify maintenance work. Each question is independent; the visible conversation is a session transcript. Check answers against the cited manual and approved site procedures.
The current app is a **local pilot**. It does not operate machines or certify maintenance work. The last four successful text exchanges provide follow-up context. Starting a new chat, changing manuals, or changing between live/example modes clears that context. Check answers against the cited manual and approved site procedures.

## Quick start

Expand All @@ -62,32 +62,43 @@ mantis --reload

Open the **[product page](http://127.0.0.1:8000)** or go directly to the **[workspace](http://127.0.0.1:8000/workspace)**. The product page is at `/`; the working assistant is at `/workspace`. FastAPI serves both the UI and API; there is no separate frontend server or build step. The setup command preserves an existing `.env`. See [running and updating](docs/running.md) for alternative entry points, environment/data locations, and troubleshooting.

### 1. Explore the demo

On the product page, choose **Try the interactive demo** to explore the embedded sample. In the workspace, choose **Explore demo**, then select a suggested question. You can also open [`/workspace#demo`](http://127.0.0.1:8000/workspace#demo) directly. Demo mode returns excerpts from an illustrative training manual. It makes no AI calls and does not describe real equipment service procedures.
### 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.

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.

### 2. Connect your manuals

Set `OPENAI_API_KEY` in the local `.env` file, then restart the server. Upload a text-based PDF, optionally label its equipment model, and select it before asking a question. Defaults allow 20 MB and 300 pages per PDF, with up to 30 manuals per workspace.

Manual text is sent to OpenAI for embeddings; questions and retrieved excerpts are sent for answer generation. The original PDF stays in the local database. See [configuration and data flow](docs/configuration.md).
Manual text is sent to OpenAI for embeddings; questions, recent text context, photo observations, and retrieved excerpts are sent for answer generation. The original PDF stays in the local database. See [configuration and data flow](docs/configuration.md).

### 3. Show the alarm

In live mode, attach one JPEG, PNG, or WebP photo (up to 8 MB and 20 megapixels) beside the message. Mantis sends it to OpenAI to read visible details and alarm text. With a selected manual, those observations inform retrieval before a source-backed reply is generated. Without a manual, replies are limited to observations and collecting context, with no fabricated manual citations. A photo is not a verified diagnosis.

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.

### 3. Verify the source
### 4. Verify the source

Select a citation to inspect its passage or open the PDF at the referenced page. A retrieval cutoff can return an insufficient-evidence response. Valid source identifiers do **not** prove that every generated claim is supported; a representative answer-quality evaluation is still needed.

## How it works

**PDF → page-local chunks → embeddings → selected-manual retrieval → structured answer → validated source IDs.**

FastAPI handles requests; SQLite stores manuals, chunks, and embeddings. The frontend is plain HTML/CSS/JavaScript, organized into product and workspace pages with shared API access. Duplicate detection and quota enforcement are serialized in a write transaction. An ASGI body limiter rejects oversized uploads before multipart parsing.
FastAPI handles requests; SQLite stores manuals, chunks, and embeddings. The frontend is plain HTML/CSS/JavaScript, organized into a compact product page and one working chat. Duplicate detection and quota enforcement are serialized in a write transaction. An ASGI body limiter rejects oversized uploads before multipart/JSON parsing.

Read the [architecture guide](docs/architecture.md) for retrieval behavior, concurrency, isolation, and scale boundaries.

## Quality and current limits

- **24 regression tests** cover real PDF extraction with a fake provider, storage isolation, persistence, deletion, concurrency, request limits, and citation handling.
- **8 frontend regressions** cover failed/stale demo requests, responsive source-inspector reveal, and reduced-motion behavior.
- **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.
- **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
6 changes: 3 additions & 3 deletions docs/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ The engineer remains responsible for checking the actual manual and following ap
- 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.
- A labeled, offline demonstration that returns illustrative training excerpts.
- 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.

## Research and next steps

The original notebooks explore Whisper transcription and Grounding DINO object detection. These are research artifacts, not integrated voice or visual-assistance features.
The original notebooks explore Whisper transcription and Grounding DINO object detection. These are research artifacts, not integrated speech or object-detection features. Live photo reading uses the chat provider, not the historical object detector.

The next product steps are representative retrieval evaluation, authenticated team workspaces, and a deliberate shared-deployment design. Speech and vision can then build on a reliable manual-to-answer workflow.
The next product steps are representative retrieval evaluation, authenticated team workspaces, and a deliberate shared-deployment design. The live photo request path is implemented and tested with a fake provider; real visual accuracy, provider compatibility, and grounded-answer quality need evaluation. Speech remains research work.

## Project background

Expand Down
6 changes: 4 additions & 2 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,11 @@ curl --cookie data/dev.cookies \
http://127.0.0.1:8000/api/questions
```

Real questions use `demo: false` and the selected manual's `document_id`, returned by the upload/list endpoints. Each question is independent. Responses contain `answer`, `sources`, `insufficient_evidence`, and `demo`. A source contains its document identifier, name, page, and text.
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.

For real PDF uploads, configure the provider first. Uploaded text is sent for embedding, and retrieved passages/questions are sent for answer generation. Duplicate detection can reuse an existing document; a new upload can incur provider usage.
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.

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.

## Expected errors

Expand Down
6 changes: 3 additions & 3 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ flowchart LR

## Indexing and persistence

`mantis/middleware.py` bounds upload bodies before multipart parsing, including chunked requests and misleading Content-Length headers. File-size, page-count, and chunk-count limits also bound accepted input. Scan-only PDFs need OCR before upload.
`mantis/middleware.py` bounds upload bodies before multipart/JSON parsing, including chunked requests and misleading Content-Length headers. Question JSON bodies have a fixed 12 MB cap. File-size, page-count, and chunk-count limits also bound accepted input. Scan-only PDFs need OCR before upload.

`mantis/rag.py` extracts overlapping chunks within individual pages, preserving neighboring lines. OpenAI embeds each chunk once, in batches. `mantis/store.py` stores the original PDF, equipment label, chunks, embeddings, and embedding model in SQLite.

Expand All @@ -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.

Each question is independent. The visible chat is a session transcript, not model conversation memory.
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.

## Workspace boundary

Expand All @@ -44,7 +44,7 @@ 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 demo and workspace share an API client module. Product navigation uses real section anchors and links into the workspace. Demo mode is activated by `/workspace#demo`.
`/` 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.

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.

Expand Down
4 changes: 2 additions & 2 deletions docs/assets/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

- `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.png`: screenshot of the real product landing page.
- `workspace.png`: screenshot of the actual local application with no private manuals or credentials.
- `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.

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 added 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 removed docs/assets/product.png
Binary file not shown.
Binary file added 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.
Binary file removed docs/assets/workspace.png
Binary file not shown.
4 changes: 2 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ For a new setup, copy `.env.example` to `.env` and configure the key locally. `.
| Setting | Default | Purpose |
| ------------------------ | ------------------------ | ---------------------------------------------------------- |
| `OPENAI_API_KEY` | empty | Required for real uploads and questions |
| `MANTIS_CHAT_MODEL` | `gpt-4o-mini` | Must support strict JSON schema outputs |
| `MANTIS_CHAT_MODEL` | `gpt-4o-mini` | Must support image input and strict JSON schema outputs |
| `MANTIS_EMBEDDING_MODEL` | `text-embedding-3-small` | Used for new manual indexes |
| `MANTIS_DATA_DIR` | `data` | SQLite storage directory |
| `MANTIS_MAX_UPLOAD_MB` | `20` | Server file limit; update frontend copy if changed |
Expand All @@ -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 and retrieved excerpts are sent for answer generation. The original PDF remains in the local database. Demo mode makes no AI calls and does not upload local documents.
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.

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
Loading
Loading