|
|
--- |
|
|
title: Prototyp Chatbot Kontextanalyse |
|
|
emoji: 📝 |
|
|
colorFrom: blue |
|
|
colorTo: yellow |
|
|
sdk: gradio |
|
|
python_version: 3.13 |
|
|
app_file: app.py |
|
|
short_description: Aktueller Prototyp für KI-gestützte Kontextanalysen. |
|
|
--- |
|
|
|
|
|
|
|
|
# KI-gestütze Kontextanalysen für Länderevaluierungen |
|
|
This is the code repository for the DEval project "Durchführung und Unterstützung von KI-gestützten Text-und Datenanalysen und deren Aufbereitung in strukturierter Form im Bereich Länderkontexte". |
|
|
|
|
|
--- |
|
|
|
|
|
## Table of Contents |
|
|
|
|
|
- **[Get Started](#get-started)** |
|
|
|
|
|
- [Set up `.env` file](#set-up-env-file) |
|
|
- [Set up the environment](#set-up-the-environment) |
|
|
- [Setup for Langfuse Prompt Management](#setup-for-langfuse-prompt-management) |
|
|
|
|
|
- **[Run the code](#run-the-code)** |
|
|
|
|
|
- **[Contributing](#contributing)** |
|
|
|
|
|
- [Deploy code changes to HuggingFace Space](#deploy-code-changes-to-huggingface-space) |
|
|
--- |
|
|
|
|
|
## Get started |
|
|
|
|
|
### Set up `.env` file |
|
|
To run, the project expects secret keys from a `.env` file. Locally set up this `.env` file. You require an `AWS_ACCESS_KEY_ID` and an `AWS_SECRET_ACCESS_KEY` to make connection to Amazon Bedrock LLMs and embedding models. Furthermore, API keys for the Langfuse integration are needed. The latter you can acquire after setting up a Langfuse project in the Langfuse GUI, either through a local setup or via Langfuse Cloud. |
|
|
|
|
|
Here how the `.env` file should look like: |
|
|
|
|
|
``` |
|
|
# .env |
|
|
# AWS keys |
|
|
AWS_ACCESS_KEY_ID= # Your AWS access key |
|
|
AWS_SECRET_ACCESS_KEY= # Your AWS secret access key |
|
|
|
|
|
# Langfuse credentials |
|
|
LANGFUSE_PUBLIC_API_KEY= # Your Langfuse public API key |
|
|
LANGFUSE_SECRET_API_KEY= # Your Langfuse secret API key |
|
|
LANGFUSE_HOST="https://cloud.langfuse.com" # EU server for langfuse Cloud, can be different for other deployments |
|
|
``` |
|
|
**Note**: Due to security reasons, this file should not be committed to version control! |
|
|
|
|
|
|
|
|
### Set up the environment |
|
|
We use `uv` as a python and our package dependency manager. Follow these [instructions](https://docs.astral.sh/uv/getting-started/installation/) to install with the standalone installer and `curl` |
|
|
|
|
|
Next, to set up the local dependencies. You can find further information [here](https://docs.astral.sh/uv/guides/projects/#managing-dependencies) |
|
|
```Bash |
|
|
uv sync |
|
|
``` |
|
|
|
|
|
This should give you a package structure like this with a `.venv` directory: |
|
|
``` |
|
|
. |
|
|
├── .venv |
|
|
├── .python-version |
|
|
├── app.py |
|
|
├── pyproject.toml |
|
|
├── README.md |
|
|
└── uv.lock |
|
|
``` |
|
|
|
|
|
#### uv.lock |
|
|
`uv.lock` is a cross-platform lockfile that contains exact information about the project's dependencies. Unlike the `pyproject.toml` which is used to specify the broad requirements of the project, the lockfile contains the exact resolved versions that are installed in the project environment via `uv`. This file should be checked into version control, allowing for consistent and reproducible installations across machines. `uv.lock` is a human-readable TOML file but is managed by `uv` and should NOT be edited manually. |
|
|
|
|
|
Alternatively, with a different dependency manager such as `venv` install directly from `pyproject.toml`. |
|
|
```Bash |
|
|
(.venv) $ pip install . |
|
|
``` |
|
|
**Note**: the dependencies then need to be documented manually in the `pyproject.toml`. |
|
|
|
|
|
|
|
|
### Setup for Langfuse Prompt Management |
|
|
Langfuse Prompt Management is used within this project. Therefore, setting up the prompt templates within Langfuse is mandatory. As the prompts directly integrate with the code, alignment is necessary. Current setup requirements can be provided by the maintainers. |
|
|
|
|
|
|
|
|
## Run the code |
|
|
After installing the needed dependencies for the project and setting up the environment, execute the code from the root of the repository by running the `app.py` script via `uv` with the following command: |
|
|
|
|
|
```Bash |
|
|
uv run app.py |
|
|
``` |
|
|
|
|
|
You will see the logging in the terminal and receive a link to access the currently locally hosted Gradio User Interface. |
|
|
|
|
|
|
|
|
## Contributing |
|
|
|
|
|
### Deploy code changes to HuggingFace Space |
|
|
|
|
|
#### Option 1: Manually force pushing to Space from `main` |
|
|
|
|
|
1. Install HuggingFace CLI via uv |
|
|
``` |
|
|
uv pip install -U "huggingface_hub[cli]" |
|
|
``` |
|
|
2. Log into HuggingFace via the Terminal |
|
|
Important: use `uv run...` and then the command, if not it will not run it from the uv environment! |
|
|
``` |
|
|
uv run huggingface-cli login |
|
|
``` |
|
|
3. Verify as which user you are logged in |
|
|
``` |
|
|
uv run huggingface-cli whoami |
|
|
``` |
|
|
4. Add HuggingFace Space as 2nd remote |
|
|
``` |
|
|
git remote add space https://huggingface.co/spaces/evaluatorhub42/Prototyp_Chatbot_Kontextanalyse_2 |
|
|
``` |
|
|
5. Check to have 2x remotes with command: |
|
|
``` |
|
|
git remote -v |
|
|
``` |
|
|
6. Force push current status of main branch to Space |
|
|
``` |
|
|
git push --force space main |
|
|
``` |
|
|
|
|
|
#### Option 2: Automatic Sync with GitHub Actions (Recommended for Ongoing Synchronicity) |
|
|
This keeps the Space in sync every time we update the main branch. |
|
|
Steps: |
|
|
1. Add the HF token as a secret called `HF_TOKEN` in your GitHub repository's settings (Settings → Secrets and variables → Actions). |
|
|
2. Add a workflow YAML file (e.g., `.github/workflows/push_to_hf_space.yml`) to the GitHub repo. More infos on setting up a GitHub action here in the HuggingFace docs: https://huggingface.co/docs/hub/spaces-github-actions |
