qraken-remote-chatbot 0.1.0__tar.gz

qraken_remote_chatbot-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+
+# Local test config for the dummy site: holds a real client key.
+dummy/.env

qraken_remote_chatbot-0.1.0/GETTING_STARTED.md

@@ -0,0 +1,198 @@
+# Adding the chatbot to your site
+
+A visitor asks a question in plain language; the chatbot turns it into a database
+query, runs it against the knowledge graph, and answers in prose.
+
+You install one Python package and add one `<script>` tag. You do **not** install
+or run any of the knowledge-graph machinery — that stays on the QRAKEN server.
+
+---
+
+## What you need
+
+**From whoever runs the QRAKEN server, two things:**
+
+| | Looks like | What it is |
+|---|---|---|
+| **Client key** | `qrk_x7Kd…` | Identifies your site and decides which graphs you may query |
+| **Graph name** | `something.ttql` | The knowledge graph your chatbot answers about |
+
+**From your own AI provider account, one thing:**
+
+| | Looks like | What it is |
+|---|---|---|
+| **Provider API key** | `sk-ant-…` | Your Anthropic / OpenAI / Google key. Your account pays for the questions your visitors ask. |
+
+Anthropic keys come from [console.anthropic.com](https://console.anthropic.com/settings/keys),
+OpenAI's from [platform.openai.com](https://platform.openai.com/api-keys). Put a
+small spending limit on the key while you experiment.
+
+---
+
+## 1. Install
+
+```bash
+pip install qraken-remote-chatbot
+```
+
+## 2. Keep the keys out of your code
+
+Both keys are secrets. Put them in your environment — the same place you keep
+your database password — never in a source file and never in a template.
+
+```bash
+export QRAKEN_TENANT_TOKEN="qrk_..."          # from the QRAKEN operator
+export QRAKEN_TTQL="something.ttql"           # the graph name they gave you
+export QRAKEN_LLM_API_KEY="sk-ant-..."        # yours
+export QRAKEN_LLM_PROVIDER="anthropic"        # or openai, gemini
+```
+
+If you keep a `.env` file, make sure it is in `.gitignore` before you write a key
+into it.
+
+## 3. Register it in your Flask app
+
+```python
+from qraken_remote_chatbot import QrakenConfig, create_blueprint
+
+app.register_blueprint(
+    create_blueprint(QrakenConfig.from_env()),
+    url_prefix="/qraken",
+)
+```
+
+`QrakenConfig.from_env()` reads the four variables above. To set anything in code
+instead, pass it directly:
+
+```python
+QrakenConfig.from_env(
+    title="Ask the collection",
+    subtitle="Questions about the archive, in plain language.",
+    accent_color="#8a4b2a",
+)
+```
+
+## 4. Add it to a page
+
+```html
+<div id="qraken-chat"></div>
+<script src="/qraken/widget.js" data-base="/qraken" defer></script>
+```
+
+That is the whole front-end integration. A chat launcher appears in the corner;
+your visitor presses **Start a conversation**, gets a greeting describing what the
+graph can answer, and asks away.
+
+The widget renders inside a *shadow root*, so your site's CSS cannot affect it and
+its styles cannot affect your site. It loads no external code and needs no build
+step.
+
+---
+
+## Check it works
+
+Open the page and press the launcher. If the greeting describes the actual
+contents of the graph, everything is connected.
+
+If not, the answer is almost always in **your server's log**, which is written to
+be read:
+
+| In your log | What to do |
+|---|---|
+| `the anthropic provider rejected the configured llm_api_key` | wrong key, or `QRAKEN_LLM_PROVIDER` names a provider the key does not belong to |
+| `QRAKEN requires this client to send its own LLM provider key` | `QRAKEN_LLM_API_KEY` is not set |
+| `QRAKEN rejected this client key` | the client key is wrong, or has been rotated or disabled |
+| `QRAKEN returned its fallback greeting` | no model answered — visitors are seeing a generic message |
+| `TTQL '…' is not allowed for this client` | `QRAKEN_TTQL` names a graph your key may not query — ask the operator |
+
+Your visitors never see any of that. They get a short, plain apology, because the
+details would tell them about servers and services that are none of their
+business.
+
+---
+
+## Two layouts
+
+**Bubble** (the default) — a launcher in the corner opening a floating panel. What
+you want on a page that has its own content.
+
+**Inline** — the chat sits in the page, no launcher, nothing floating. For a page
+whose whole purpose is asking questions. Give the container a height:
+
+```html
+<div id="qraken-chat" style="height: 560px"></div>
+<script src="/qraken/widget.js" data-base="/qraken" data-display="inline" defer></script>
+```
+
+## Settings worth knowing
+
+Everything below is optional, passed to `QrakenConfig`:
+
+| Setting | Default | What it does |
+|---|---|---|
+| `title`, `subtitle` | | The panel header |
+| `start_label`, `placeholder` | | Button and input wording |
+| `accent_color` | `#2a78d6` | Matches the widget to your site |
+| `position` | `right` | Which corner the launcher sits in |
+| `display` | `bubble` | `bubble` or `inline` |
+| `show_sparql` | `False` | Adds a "show the query" toggle under each answer. Useful for expert audiences, noise for everyone else. |
+| `llm_model` | | A specific model. Leave unset and the server picks a sensible default. |
+| `retrieve_literals` | `False` | Helps when questions name specific titles, people or places |
+| `session_ttl_s` | `3600` | How long an idle conversation is remembered |
+| `max_question_chars` | `2000` | Rejects oversized questions before they cost anything |
+
+## Answers take time
+
+A question runs three steps on the server: translate to a query, run it against
+the graph, put the result into words. Ten to forty seconds is normal, and the
+widget shows a thinking indicator throughout.
+
+If your site sits behind a reverse proxy (nginx, Apache, a CDN), make sure its
+read timeout is **at least 180 seconds** for the `/qraken/` path. A proxy that
+gives up at 60s will cut off answers the server is still producing — which looks
+like a broken chatbot but is only impatience.
+
+## In production
+
+Conversations are remembered on your server, not in the browser, so a visitor
+cannot tamper with the context sent to the graph. The default store keeps them in
+memory, which is right for **one** worker process.
+
+If you run several workers (gunicorn with `-w 4`, several containers), each has
+its own memory and a visitor's follow-up question may land on a worker that has
+never heard of them. Either pin sessions to a worker at the load balancer, or
+provide shared storage:
+
+```python
+from qraken_remote_chatbot import SessionStore, create_blueprint
+
+class RedisSessionStore(SessionStore):
+    def create(self, data): ...     # return a new session id
+    def get(self, session_id): ...  # return the stored dict, or None
+    def update(self, session_id, data): ...
+    def delete(self, session_id): ...
+
+app.register_blueprint(
+    create_blueprint(config, store=RedisSessionStore(url)),
+    url_prefix="/qraken",
+)
+```
+
+## What not to do
+
+- **Never put either key in a template, a JavaScript file, or anything the browser
+  downloads.** Both belong on the server. The widget is built so it never needs
+  them: it talks only to your own domain.
+- **Do not commit a `.env` file.** Add it to `.gitignore` first.
+- **Do not proxy `/qraken/` to the QRAKEN server directly.** The package exists to
+  sit in between; bypassing it would mean putting your keys in the browser.
+
+## Getting help
+
+Something wrong in the chatbot's *answers* — wrong numbers, missing records,
+misread questions — is about the graph or the model, so it goes to whoever runs
+the QRAKEN server.
+
+Something wrong in the *installation* — the widget not appearing, an error in your
+log, a question that never returns — is in this package:
+https://github.com/RemoGrillo/QRAKEN_remote_chatbot/issues

qraken_remote_chatbot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remo Grillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qraken_remote_chatbot-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: qraken-remote-chatbot
+Version: 0.1.0
+Summary: Embed a QRAKEN knowledge-graph chatbot in any site: a chat widget plus the server-side proxy that keeps your API keys out of the browser.
+Project-URL: Homepage, https://github.com/RemoGrillo/QRAKEN_remote_chatbot
+Project-URL: Documentation, https://github.com/RemoGrillo/QRAKEN_remote_chatbot#readme
+Project-URL: Issues, https://github.com/RemoGrillo/QRAKEN_remote_chatbot/issues
+Project-URL: Source, https://github.com/RemoGrillo/QRAKEN_remote_chatbot
+Author-email: Remo Grillo <rgrillo@itatti.harvard.edu>
+License: MIT
+License-File: LICENSE
+Keywords: chatbot,cidoc-crm,digital-humanities,flask,knowledge-graph,nl2sparql,qraken,rdf,sparql,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# QRAKEN Remote Chatbot
+
+Embed a QRAKEN knowledge-graph chatbot in your website. Your visitors ask questions
+in plain language; QRAKEN turns them into SPARQL, runs them against your graph, and
+answers in prose.
+
+You install one pip package and add one `<script>` tag. You do **not** install the
+QRAKEN stack — that runs on a QRAKEN server you point at.
+
+## How it fits together
+
+```
+Visitor's browser          Your Flask server              QRAKEN server
+┌────────────────┐         ┌──────────────────┐          ┌─────────────────┐
+│ chat widget    │ ──────► │ this package     │ ───────► │ /embed API      │
+│ (no keys)      │ ◄────── │ (holds the keys) │ ◄─────── │ NTQ · SPARQL    │
+└────────────────┘         └──────────────────┘          │ · the model     │
+     same-origin                                          └─────────────────┘
+```
+
+The browser only ever talks to your own server, so there is **no CORS to configure**
+and **no credential in the page**. Your client key and your LLM provider key stay in
+your Flask process.
+
+## Install
+
+```bash
+pip install qraken-remote-chatbot
+```
+
+New to this? **[GETTING_STARTED.md](GETTING_STARTED.md)** is the step-by-step
+version, written for someone adding the chatbot to a site for the first time.
+
+## Configure
+
+You need two things:
+
+1. A **client key** (`qrk_…`) from the QRAKEN operator, issued from their admin
+   dashboard. It also decides which graphs you may query.
+2. An **LLM provider key** of your own — OpenAI, Anthropic, Gemini, … Your account
+   is billed for the questions your visitors ask.
+
+Keep both in the environment, never in code:
+
+```bash
+export QRAKEN_TENANT_TOKEN=qrk_...
+export QRAKEN_LLM_API_KEY=sk-ant-...
+export QRAKEN_LLM_PROVIDER=anthropic
+export QRAKEN_TTQL=my-graph.ttql
+```
+
+## Add it to your app
+
+```python
+import os
+from flask import Flask
+from qraken_remote_chatbot import QrakenConfig, create_blueprint
+
+app = Flask(__name__)
+
+app.register_blueprint(create_blueprint(QrakenConfig(
+    tenant_token = os.environ["QRAKEN_TENANT_TOKEN"],
+    llm_api_key  = os.environ["QRAKEN_LLM_API_KEY"],
+    llm_provider = "anthropic",
+    ttql_name    = "my-graph.ttql",
+)), url_prefix="/qraken")
+```
+
+Or, reading everything from the environment:
+
+```python
+app.register_blueprint(create_blueprint(QrakenConfig.from_env()), url_prefix="/qraken")
+```
+
+Then, in any page:
+
+```html
+<div id="qraken-chat"></div>
+<script src="/qraken/widget.js" data-base="/qraken" defer></script>
+```
+
+That is the whole integration. The widget renders a launcher in the corner; the
+visitor presses **Start a conversation**, gets a greeting describing what the graph
+can answer, and chats from there.
+
+## Configuration reference
+
+| Option | Default | What it does |
+|---|---|---|
+| `tenant_token` | — | **Required.** Your client key from the QRAKEN operator. |
+| `ttql_name` | — | **Required.** The graph to answer about, by TTQL filename. |
+| `llm_api_key` | `None` | Your provider key. Omit only if the operator covers your usage. |
+| `llm_provider` | `anthropic` | `openai` · `anthropic` · `gemini` · `harvard_bedrock` · `lmstudio` |
+| `llm_model` | `None` | Model id; the server picks a default when unset. |
+| `qraken_url` | `https://qrakenchatbot.remogrillo.me` | The QRAKEN server. |
+| `timeout_s` | `180` | A turn runs translation, a SPARQL query and an answer — keep this generous. |
+| `session_ttl_s` | `3600` | How long an idle conversation is remembered. |
+| `retrieve_literals` | `False` | Value grounding, when the operator has built a Sonar index. |
+| `max_question_chars` | `2000` | Rejects oversized questions before they cost anything. |
+| `title` / `subtitle` / `start_label` / `placeholder` | — | Widget wording. |
+| `show_sparql` | `False` | Reveal the generated query behind a toggle. |
+| `display` | `bubble` | `bubble` — launcher + floating panel; `inline` — the chat fills its container. |
+| `accent_color` | `#2a78d6` | Widget accent. |
+| `position` | `right` | Which corner the launcher sits in. Ignored when inline. |
+| `retrieve_literals` | `False` | Value grounding: inject question-relevant literal values into the prompt. |
+
+Only the appearance options ever reach the browser — `public_settings()` builds the
+widget's config from an explicit list, so a credential cannot leak by being forgotten.
+
+## Widget script attributes
+
+| Attribute | Default | Meaning |
+|---|---|---|
+| `data-base` | `/qraken` | Must match your `url_prefix`. |
+| `data-target` | `#qraken-chat` | CSS selector of the mount element. |
+| `data-open` | `false` | Open the panel on load. |
+
+The widget renders inside a **shadow root**: your site's CSS cannot affect it, and
+its styles cannot affect your site. It has no dependencies and no build step.
+
+## Two layouts
+
+**Bubble** (default) — a launcher in the corner opening a floating panel. What you
+want on a page that has its own content.
+
+**Inline** — the chat sits in the page where you put the mount element, with no
+launcher and nothing floating. For a page whose whole purpose is the chatbot. Give
+the container a height; the widget fills it.
+
+```html
+<div id="qraken-chat" style="height: 560px"></div>
+<script src="/qraken/widget.js" data-base="/qraken" data-display="inline" defer></script>
+```
+
+`data-display` overrides the server setting for one page; `display="inline"` in
+`QrakenConfig` changes the default for all of them.
+
+## Who pays for the questions
+
+Set `llm_api_key` and your provider account is billed for your visitors' questions.
+
+The QRAKEN operator decides, per client, whether you are *allowed* to omit it and
+fall back to their key — off by default. If it is off and you send no key, every
+question fails and your log says exactly which setting to change. Your visitors
+only ever see a generic apology.
+
+## Endpoints this blueprint adds
+
+| Route | Purpose |
+|---|---|
+| `POST /qraken/session` | Start a conversation; returns the icebreaker. |
+| `POST /qraken/message` | Ask one question. |
+| `POST /qraken/end` | Drop a conversation. |
+| `GET /qraken/download/<token>.<csv\|json>` | Proxy a result file. |
+| `GET /qraken/widget.js`, `/widget.css`, `/config.json` | Widget assets. |
+
+## Running more than one worker
+
+Conversations are held server-side so the browser cannot forge them. The default
+store is an in-process dictionary, which is correct for a single worker. Behind
+several workers, implement `SessionStore` over shared storage:
+
+```python
+from qraken_remote_chatbot import SessionStore, create_blueprint
+
+class RedisSessionStore(SessionStore):
+    ...   # create / get / update / delete
+
+app.register_blueprint(
+    create_blueprint(config, store=RedisSessionStore(redis_url)),
+    url_prefix="/qraken",
+)
+```
+
+## What the visitor sees when something fails
+
+Upstream errors never reach the page verbatim — internal service names, paths and
+query details stay in your server log. The visitor gets a short, safe sentence, and
+an expired conversation offers its way back to a new one.
+
+## Try it
+
+```bash
+pip install -e ".[dev]"
+python examples/demo_app.py       # http://localhost:5000
+pytest                            # runs offline against a stubbed server
+```
+
+## Requirements
+
+Python 3.9+, Flask 2.0+, and network access to a QRAKEN server.
+
+## License
+
+MIT

qraken_remote_chatbot-0.1.0/README.md

@@ -0,0 +1,195 @@
+# QRAKEN Remote Chatbot
+
+Embed a QRAKEN knowledge-graph chatbot in your website. Your visitors ask questions
+in plain language; QRAKEN turns them into SPARQL, runs them against your graph, and
+answers in prose.
+
+You install one pip package and add one `<script>` tag. You do **not** install the
+QRAKEN stack — that runs on a QRAKEN server you point at.
+
+## How it fits together
+
+```
+Visitor's browser          Your Flask server              QRAKEN server
+┌────────────────┐         ┌──────────────────┐          ┌─────────────────┐
+│ chat widget    │ ──────► │ this package     │ ───────► │ /embed API      │
+│ (no keys)      │ ◄────── │ (holds the keys) │ ◄─────── │ NTQ · SPARQL    │
+└────────────────┘         └──────────────────┘          │ · the model     │
+     same-origin                                          └─────────────────┘
+```
+
+The browser only ever talks to your own server, so there is **no CORS to configure**
+and **no credential in the page**. Your client key and your LLM provider key stay in
+your Flask process.
+
+## Install
+
+```bash
+pip install qraken-remote-chatbot
+```
+
+New to this? **[GETTING_STARTED.md](GETTING_STARTED.md)** is the step-by-step
+version, written for someone adding the chatbot to a site for the first time.
+
+## Configure
+
+You need two things:
+
+1. A **client key** (`qrk_…`) from the QRAKEN operator, issued from their admin
+   dashboard. It also decides which graphs you may query.
+2. An **LLM provider key** of your own — OpenAI, Anthropic, Gemini, … Your account
+   is billed for the questions your visitors ask.
+
+Keep both in the environment, never in code:
+
+```bash
+export QRAKEN_TENANT_TOKEN=qrk_...
+export QRAKEN_LLM_API_KEY=sk-ant-...
+export QRAKEN_LLM_PROVIDER=anthropic
+export QRAKEN_TTQL=my-graph.ttql
+```
+
+## Add it to your app
+
+```python
+import os
+from flask import Flask
+from qraken_remote_chatbot import QrakenConfig, create_blueprint
+
+app = Flask(__name__)
+
+app.register_blueprint(create_blueprint(QrakenConfig(
+    tenant_token = os.environ["QRAKEN_TENANT_TOKEN"],
+    llm_api_key  = os.environ["QRAKEN_LLM_API_KEY"],
+    llm_provider = "anthropic",
+    ttql_name    = "my-graph.ttql",
+)), url_prefix="/qraken")
+```
+
+Or, reading everything from the environment:
+
+```python
+app.register_blueprint(create_blueprint(QrakenConfig.from_env()), url_prefix="/qraken")
+```
+
+Then, in any page:
+
+```html
+<div id="qraken-chat"></div>
+<script src="/qraken/widget.js" data-base="/qraken" defer></script>
+```
+
+That is the whole integration. The widget renders a launcher in the corner; the
+visitor presses **Start a conversation**, gets a greeting describing what the graph
+can answer, and chats from there.
+
+## Configuration reference
+
+| Option | Default | What it does |
+|---|---|---|
+| `tenant_token` | — | **Required.** Your client key from the QRAKEN operator. |
+| `ttql_name` | — | **Required.** The graph to answer about, by TTQL filename. |
+| `llm_api_key` | `None` | Your provider key. Omit only if the operator covers your usage. |
+| `llm_provider` | `anthropic` | `openai` · `anthropic` · `gemini` · `harvard_bedrock` · `lmstudio` |
+| `llm_model` | `None` | Model id; the server picks a default when unset. |
+| `qraken_url` | `https://qrakenchatbot.remogrillo.me` | The QRAKEN server. |
+| `timeout_s` | `180` | A turn runs translation, a SPARQL query and an answer — keep this generous. |
+| `session_ttl_s` | `3600` | How long an idle conversation is remembered. |
+| `retrieve_literals` | `False` | Value grounding, when the operator has built a Sonar index. |
+| `max_question_chars` | `2000` | Rejects oversized questions before they cost anything. |
+| `title` / `subtitle` / `start_label` / `placeholder` | — | Widget wording. |
+| `show_sparql` | `False` | Reveal the generated query behind a toggle. |
+| `display` | `bubble` | `bubble` — launcher + floating panel; `inline` — the chat fills its container. |
+| `accent_color` | `#2a78d6` | Widget accent. |
+| `position` | `right` | Which corner the launcher sits in. Ignored when inline. |
+| `retrieve_literals` | `False` | Value grounding: inject question-relevant literal values into the prompt. |
+
+Only the appearance options ever reach the browser — `public_settings()` builds the
+widget's config from an explicit list, so a credential cannot leak by being forgotten.
+
+## Widget script attributes
+
+| Attribute | Default | Meaning |
+|---|---|---|
+| `data-base` | `/qraken` | Must match your `url_prefix`. |
+| `data-target` | `#qraken-chat` | CSS selector of the mount element. |
+| `data-open` | `false` | Open the panel on load. |
+
+The widget renders inside a **shadow root**: your site's CSS cannot affect it, and
+its styles cannot affect your site. It has no dependencies and no build step.
+
+## Two layouts
+
+**Bubble** (default) — a launcher in the corner opening a floating panel. What you
+want on a page that has its own content.
+
+**Inline** — the chat sits in the page where you put the mount element, with no
+launcher and nothing floating. For a page whose whole purpose is the chatbot. Give
+the container a height; the widget fills it.
+
+```html
+<div id="qraken-chat" style="height: 560px"></div>
+<script src="/qraken/widget.js" data-base="/qraken" data-display="inline" defer></script>
+```
+
+`data-display` overrides the server setting for one page; `display="inline"` in
+`QrakenConfig` changes the default for all of them.
+
+## Who pays for the questions
+
+Set `llm_api_key` and your provider account is billed for your visitors' questions.
+
+The QRAKEN operator decides, per client, whether you are *allowed* to omit it and
+fall back to their key — off by default. If it is off and you send no key, every
+question fails and your log says exactly which setting to change. Your visitors
+only ever see a generic apology.
+
+## Endpoints this blueprint adds
+
+| Route | Purpose |
+|---|---|
+| `POST /qraken/session` | Start a conversation; returns the icebreaker. |
+| `POST /qraken/message` | Ask one question. |
+| `POST /qraken/end` | Drop a conversation. |
+| `GET /qraken/download/<token>.<csv\|json>` | Proxy a result file. |
+| `GET /qraken/widget.js`, `/widget.css`, `/config.json` | Widget assets. |
+
+## Running more than one worker
+
+Conversations are held server-side so the browser cannot forge them. The default
+store is an in-process dictionary, which is correct for a single worker. Behind
+several workers, implement `SessionStore` over shared storage:
+
+```python
+from qraken_remote_chatbot import SessionStore, create_blueprint
+
+class RedisSessionStore(SessionStore):
+    ...   # create / get / update / delete
+
+app.register_blueprint(
+    create_blueprint(config, store=RedisSessionStore(redis_url)),
+    url_prefix="/qraken",
+)
+```
+
+## What the visitor sees when something fails
+
+Upstream errors never reach the page verbatim — internal service names, paths and
+query details stay in your server log. The visitor gets a short, safe sentence, and
+an expired conversation offers its way back to a new one.
+
+## Try it
+
+```bash
+pip install -e ".[dev]"
+python examples/demo_app.py       # http://localhost:5000
+pytest                            # runs offline against a stubbed server
+```
+
+## Requirements
+
+Python 3.9+, Flask 2.0+, and network access to a QRAKEN server.
+
+## License
+
+MIT