Metadata-Version: 2.5
Name: fds-bot
Version: 0.2.2
Summary: Locally-run study assistant for the Foundations of Data Science course at UZH
Project-URL: Homepage, https://www.ifi.uzh.ch/en/dast.html
Author-email: Christoph Mayer <mayer@ifi.uzh.ch>, Giuseppe Doda <giuseppe.doda@uzh.ch>
License-Expression: MIT
License-File: LICENSE
Keywords: UZH,chatbot,education,fds,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: cryptography<49; sys_platform == 'darwin' and platform_machine == 'x86_64'
Requires-Dist: cryptography>=49; sys_platform != 'darwin' or platform_machine != 'x86_64'
Requires-Dist: faiss-cpu<1.15,>=1.12; python_version >= '3.14'
Requires-Dist: faiss-cpu==1.10.0; python_version < '3.14'
Requires-Dist: fastapi[standard-no-fastapi-cloud-cli]<0.136.0,>=0.135.2
Requires-Dist: google-genai<2,>=1.68.0
Requires-Dist: pydantic-settings<3,>=2.13.1
Requires-Dist: pymupdf<1.28,>=1.27.2.2
Requires-Dist: rapidfuzz<4,>=3.14.5
Requires-Dist: sqlmodel<0.0.38,>=0.0.37
Requires-Dist: sse-starlette<4,>=3.3.4
Requires-Dist: structlog>=25.4.0
Description-Content-Type: text/markdown

# FDS Bot

[![PyPI](https://img.shields.io/pypi/v/fds-bot.svg)](https://pypi.org/project/fds-bot/)
[![Python versions](https://img.shields.io/pypi/pyversions/fds-bot.svg)](https://pypi.org/project/fds-bot/)
[![License](https://img.shields.io/pypi/l/fds-bot.svg)](https://pypi.org/project/fds-bot/)

A locally deployable study assistant for the **Foundations of Data Science**
course at UZH.

FDS Bot answers your questions from the course's own lecture notes and nothing
else. It runs on your machine: install the app from PyPI, import the course
bundle handed out on the course page, and add a free
[Gemini API](https://ai.google.dev/) key.

## What it does

- **Answers grounded in the notes**: every reply is built from the course
  material, not from the model's general knowledge.
- **Citations you can open**: each answer names the sections it used, and a
  click opens the lecture-notes PDF at that page with the quoted lines
  highlighted.
- **Quotes checked against the source**: the verbatim lines an answer quotes
  are checked locally against the notes, and a quote that cannot be confirmed
  is flagged rather than quietly shown.
- **Section summaries**: ask it to summarize a section and it works through
  that section's whole subtree in order, not just the passages that matched.
- **Math and code render properly**: answers stream in with LaTeX and syntax
  highlighting.

It is still a language model: it can be wrong, and it can be confidently
wrong. Every answer carries its citations, so check it against the notes
before you rely on it.

## Requirements

- **Python 3.10–3.14**: check with `python3 --version` (`py --version` on
  Windows). If `pip` says *no matching distribution
  found*, install Python 3.14 or older and try again.
- **The course bundle**: `fds-bot-data-YYYY-MM-DD.tar.gz` (about 65 MB), from
  the FDS course page. It holds the lecture notes and the search indices built
  from them: course material shared only with enrolled students through the course page.
- **A Gemini API key**: free from [Google AI Studio](https://aistudio.google.com/apikey).
- **An internet connection**: the notes and the search run on your machine,
  but the answers are generated by Google's Gemini API.

## Installation

```bash
pip install fds-bot
```

If `pip` throws errors or if the install succeeds but `fds-bot` is then
"command not found", install it into its own environment instead:

```bash
pipx install fds-bot
```

Then download the course bundle from the FDS course page and **leave it
packed**, the app takes the file exactly as it downloaded.

## Running it

```bash
fds-bot
```

The server starts and your browser opens at `http://127.0.0.1:8000/`. The
terminal stays almost silent, and that is the healthy state rather than a
stalled start:

```text
fds-bot is ready: open http://127.0.0.1:8000/ in your browser.

Press Ctrl+C to stop.
```

Only errors are logged, so anything printed alongside those lines is worth
reading. The address is printed on every launch, and you can always open it
yourself.

## First launch

The first start asks for two things, right where you would chat:

- **The course bundle**: drag the downloaded `.tar.gz` onto the page, or use
  the file picker. The app copies it into its own
  data folder under `~/.fds-bot/`, so you can delete the download afterwards.
- **A Gemini API key**: paste in a free key from
  [Google AI Studio](https://aistudio.google.com/apikey) and you are ready to
  go.

## Keeping the course material up to date

When the notes are updated mid-semester, download the new file and import it
from **Settings → Course material → Replace**. That
settings card shows the build date of the bundle you have, and
`fds-bot --version` prints it next to the app version.

## Command-line options

| Option | What it does |
|---|---|
| `--host HOST` | Serve on a specific host |
| `--port PORT` | Serve on another port when 8000 is already in use |
| `--version` | Print the app version and the build date of the imported bundle |
| `--help` | Show every option, including `--host` and `--log-level` |

## Your data stays on your machine

Your API key, your conversations, your settings, and the imported course bundle
all live under `~/.fds-bot/`.

<details>
<summary>Platform requirements</summary>

Pre-built wheels cover all supported platforms, so no compiler is needed:

| Platform | Requirement |
|---|---|
| Linux | x86_64 or arm64, glibc ≥ 2.28 (Ubuntu 20.04+, Debian 10+, RHEL 8+) |
| macOS (Apple Silicon) | macOS ≥ 11 on Python 3.10–3.13; macOS ≥ 14 on Python 3.14 |
| macOS (Intel) | macOS ≥ 10.14 on Python 3.10–3.13; macOS ≥ 15 on Python 3.14 |
| Windows | AMD64 |

If `pip` reports no matching distribution, or starts *compiling* something, you
are on an unsupported combination, an older Python (3.10–3.13) is the quickest
fix.

</details>

## Support

Found a wrong answer or a bug? The app has a built-in feedback flow: select the
answers in question and click **Copy package**, and the app and model metadata are
filled in for you, then use **Open email app** or **Download .md** on the
screen that follows, and send the result to the course maintainer.

Source access is internal to the UZH DaST group. Contact
[mayer@ifi.uzh.ch](mailto:mayer@ifi.uzh.ch) or
[giuseppe.doda@uzh.ch](mailto:giuseppe.doda@uzh.ch). Contributors working from a
checkout: see `CONTRIBUTING.md`.

## License

The application code is released under the MIT License. The course bundle is
**not** covered by it: the lecture notes and everything derived from them are
licensed for use by enrolled FDS students only, and must not be redistributed.
