From 2565de4f5577e71112b7e8804ee677427c19bf87 Mon Sep 17 00:00:00 2001 From: Adam Wright Date: Fri, 4 Sep 2026 22:07:40 +0000 Subject: [PATCH 1/2] Fix the UniProt prompt, two typos, and a Quick Start that does not work The UniProt system prompt told the model "For Reactome always format citations", a copy-paste from the Reactome prompt. Reported by @GovindhKishore in #121. The rest of that PR is prompt tuning -- preferring retrieved data, citing stable identifiers -- which is a judgement call rather than a fix, and one of those changes would tend to lengthen answers, which is the opposite of what is wanted right now. Not taken. Two spelling fixes found by sweeping every prompt: "final asnwer" in the UniProt prompt, and "LLM generated reponse" in the web-search state. The Quick Start did not work as written, which is why #122, #124 and #158 all try to patch it: - step 5 ran `./bin/embeddings_manager`, whose `#!/usr/bin/env python` shebang fails outright on a system that provides only `python3`, and which needs the project's dependencies either way. Both bin scripts now say `python3`, and the documented commands use `poetry run`. - `PYTHONPATH` was to be "verified" rather than set. Nothing sets it, so verifying it tells a new contributor only that it is wrong. - OPENAI_API_KEY was never mentioned, so the final step could not work. The packaging change will delete most of this by making `poetry install` sufficient, but three people have now filed PRs against these instructions and the fix should not wait on a refactor. Co-Authored-By: Claude Opus 5 --- README.md | 26 ++++++++++++++++---------- bin/embeddings_manager | 2 +- bin/retrieval_baseline | 2 +- src/retrievers/uniprot/prompt.py | 4 ++-- src/tools/external_search/state.py | 2 +- 5 files changed, 21 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 2c2c5c8..8166be2 100644 --- a/README.md +++ b/README.md @@ -30,24 +30,30 @@ Follow these steps to run the barebones Chainlit application. ```bash poetry install ``` -4. Verify your `PYTHONPATH` environment variable includes `./src`: +4. Add your OpenAI key. The chatbot cannot answer without one: ```bash - echo $PYTHONPATH - # ./src + cp env_template .env + # then edit .env and set OPENAI_API_KEY ``` -5. List embeddings available for download: +5. Put `./src` on the `PYTHONPATH`. The entry points import from there, and + nothing sets it for you: ```bash - ./bin/embeddings_manager ls-remote + export PYTHONPATH="./src:$PYTHONPATH" ``` -6. Install your chosen embeddings: +6. List embeddings available for download. `poetry run` puts the project's + dependencies on the path: ```bash - ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX + poetry run ./bin/embeddings_manager ls-remote ``` -7. Run the Chainlit application: +7. Install your chosen embeddings. These are multi-gigabyte downloads: + ```bash + poetry run ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX ``` - chainlit run bin/chat-chainlit.py -w +8. Run the Chainlit application: + ```bash + poetry run chainlit run bin/chat-chainlit.py -w ``` -8. Access the app at http://localhost:8000 🎉 +9. Access the app at http://localhost:8000 🎉 ### Docker Setup diff --git a/bin/embeddings_manager b/bin/embeddings_manager index a7c4d74..3bf3b56 100755 --- a/bin/embeddings_manager +++ b/bin/embeddings_manager @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 import os import re diff --git a/bin/retrieval_baseline b/bin/retrieval_baseline index 89e543c..d8c1125 100755 --- a/bin/retrieval_baseline +++ b/bin/retrieval_baseline @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 """Record what each retriever returns, so a change to retrieval can be diffed. Retrieval quality has no right answer, only a "did this change". This captures diff --git a/src/retrievers/uniprot/prompt.py b/src/retrievers/uniprot/prompt.py index 7cb0910..9f5cf27 100644 --- a/src/retrievers/uniprot/prompt.py +++ b/src/retrievers/uniprot/prompt.py @@ -11,8 +11,8 @@ 2. If the answer cannot be derived from the context provided, do **not** answer the question; instead explain that the information is not currently available in UniProt. 3. Answer the question comprehensively and accurately, providing useful background information based **only** on the context. 4. keep track of **all** the sources that are directly used to derive the final answer, ensuring **every** piece of information in your response is **explicitly cited**. -5. Create Citations for the sources used to generate the final asnwer according to the following: - - For Reactome always format citations in the following format: *short_protein_name*. +5. Create Citations for the sources used to generate the final answer according to the following: + - For UniProt always format citations in the following format: *short_protein_name*. Examples: - GATA6 - NR5A2 diff --git a/src/tools/external_search/state.py b/src/tools/external_search/state.py index 034e994..322317c 100644 --- a/src/tools/external_search/state.py +++ b/src/tools/external_search/state.py @@ -9,6 +9,6 @@ class WebSearchResult(TypedDict): class SearchState(TypedDict, total=False): input: str # LLM enhanced User question - generation: str # LLM generated reponse to the user question + generation: str # LLM generated response to the user question complete: str # "Yes" or "No" to search for external resources search_results: list[WebSearchResult] # Results from searching the web From b0ee328baa527ffd63069e89bca4a5bec08a6f96 Mon Sep 17 00:00:00 2001 From: Adam Wright Date: Fri, 4 Sep 2026 22:11:47 +0000 Subject: [PATCH 2/2] Do not tell people to copy env_template for the barebones run The Quick Start said to copy env_template, which sets POSTGRES_*. chat-chainlit then builds a connection to host postgres:5432 -- real in Docker Compose, absent on a developer's machine -- and the failure surfaces only on the first message, not at startup. So the fix I made to that section reproduced the class of problem it was fixing: instructions that look right and fail later. It now writes a one-line .env with just the API key, and says why env_template is for the Docker setup instead. Co-Authored-By: Claude Opus 5 --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8166be2..2f16bb2 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,12 @@ Follow these steps to run the barebones Chainlit application. ``` 4. Add your OpenAI key. The chatbot cannot answer without one: ```bash - cp env_template .env - # then edit .env and set OPENAI_API_KEY + echo 'OPENAI_API_KEY=sk-...' > .env ``` + Do **not** copy `env_template` for this. It sets `POSTGRES_*`, which makes the + app try to reach a database at host `postgres:5432` — that exists in Docker + Compose but not on your machine, and the failure only appears on the first + message. `env_template` is for the Docker setup below. 5. Put `./src` on the `PYTHONPATH`. The entry points import from there, and nothing sets it for you: ```bash