Usable "getting started" docs in README, both interpreter and Jupyter (#953)

Author: jamesbraza

README.md

@@ -63,8 +63,10 @@ and finally answer the user question with an LLM agent.
 
 ```bash
 pip install paper-qa
+mkdir my_papers
+curl -o my_papers/PaperQA2.pdf https://arxiv.org/pdf/2409.13740
 cd my_papers
-pqa ask 'How can carbon nanotubes be manufactured at a large scale?'
+pqa ask 'What is PaperQA2?'
 ```
 
 ### Example Output
@@ -181,7 +183,7 @@ Those can be exported as `CROSSREF_API_KEY` and `SEMANTIC_SCHOLAR_API_KEY` varia
 The fastest way to test PaperQA2 is via the CLI. First navigate to a directory with some papers and use the `pqa` cli:
 
 ```bash
-$ pqa ask 'What manufacturing challenges are unique to bispecific antibodies?'
+pqa ask 'What is PaperQA2?'
 ```
 
 You will see PaperQA2 index your local PDF files, gathering the necessary metadata for each of them (using [Crossref](https://www.crossref.org/) and [Semantic Scholar](https://www.semanticscholar.org/)),
@@ -190,13 +192,13 @@ search over that index, then break the files into chunked evidence contexts, ran
 All prior answers will be indexed and stored, you can view them by querying via the `search` subcommand, or access them yourself in your `PQA_HOME` directory, which defaults to `~/.pqa/`.
 
 ```bash
-$ pqa search -i 'answers' 'antibodies'
+pqa -i 'answers' search 'ranking and contextual summarization'
 ```
 
 PaperQA2 is highly configurable, when running from the command line, `pqa --help` shows all options and short descriptions. For example to run with a higher temperature:
 
 ```bash
-$ pqa --temperature 0.5 ask 'What manufacturing challenges are unique to bispecific antibodies?'
+pqa --temperature 0.5 ask 'What is PaperQA2?'
 ```
 
 You can view all settings with `pqa view`. Another useful thing is to change to other templated settings - for example `fast` is a setting that answers more quickly and you can see it with `pqa -s fast view`
@@ -210,13 +212,13 @@ pqa -s my_new_settings --temperature 0.5 --llm foo-bar-5 save
 and then you can use it with
 
 ```bash
-pqa -s my_new_settings ask 'What manufacturing challenges are unique to bispecific antibodies?'
+pqa -s my_new_settings ask 'What is PaperQA2?'
 ```
 
 If you run `pqa` with a command which requires a new indexing, say if you change the default chunk_size, a new index will automatically be created for you.
 
 ```bash
-pqa --parsing.chunk_size 5000 ask 'What manufacturing challenges are unique to bispecific antibodies?'
+pqa --parsing.chunk_size 5000 ask 'What is PaperQA2?'
 ```
 
 You can also use `pqa` to do full-text search with use of LLMs view the search command. For example, let's save the index from a directory and give it a name:
@@ -262,7 +264,7 @@ If you are hitting rate limits, say with the OpenAI Tier 1 plan, you can add the
 For each OpenAI tier, a pre-built setting exists to limit usage.
 
 ```bash
-pqa --settings 'tier1_limits' ask 'Are there nm scale features in thermoelectric materials?'
+pqa --settings 'tier1_limits' ask 'What is PaperQA2?'
 ```
 
 This will limit your system to use the [tier1_limits](paperqa/configs/tier1_limits.json),
@@ -271,7 +273,7 @@ and slow down your queries to accommodate.
 You can also specify them manually with any rate limit string that matches the specification in the [limits](https://limits.readthedocs.io/en/stable/quickstart.html#rate-limit-string-notation) module:
 
 ```bash
-pqa --summary_llm_config '{"rate_limit": {"gpt-4o-2024-11-20": "30000 per 1 minute"}}' ask 'Are there nm scale features in thermoelectric materials?'
+pqa --summary_llm_config '{"rate_limit": {"gpt-4o-2024-11-20": "30000 per 1 minute"}}' ask 'What is PaperQA2?'
 ```
 
 Or by adding into a `Settings` object, if calling imperatively:
@@ -280,7 +282,7 @@ Or by adding into a `Settings` object, if calling imperatively:
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(
         llm_config={"rate_limit": {"gpt-4o-2024-11-20": "30000 per 1 minute"}},
         summary_llm_config={"rate_limit": {"gpt-4o-2024-11-20": "30000 per 1 minute"}},
@@ -296,7 +298,7 @@ PaperQA2's full workflow can be accessed via Python directly:
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(temperature=0.5, paper_directory="my_papers"),
 )
 ```
@@ -312,7 +314,7 @@ The answer object has the following attributes: `formatted_answer`, `answer` (an
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(temperature=0.5, paper_directory="my_papers"),
 )
 ```
@@ -323,7 +325,7 @@ answer_response = ask(
 from paperqa import Settings, agent_query
 
 answer_response = await agent_query(
-    query="What manufacturing challenges are unique to bispecific antibodies?",
+    query="What is PaperQA2?",
     settings=Settings(temperature=0.5, paper_directory="my_papers"),
 )
 ```
@@ -358,10 +360,7 @@ settings.llm = "claude-3-5-sonnet-20240620"
 settings.answer.answer_max_sources = 3
 
 # Query the Docs object to get an answer
-session = await docs.aquery(
-    "What manufacturing challenges are unique to bispecific antibodies?",
-    settings=settings,
-)
+session = await docs.aquery("What is PaperQA2?", settings=settings)
 print(session)
 ```
 
@@ -394,9 +393,7 @@ async def main() -> None:
     for doc in ("myfile.pdf", "myotherfile.pdf"):
         await docs.aadd(doc)
 
-    session = await docs.aquery(
-        "What manufacturing challenges are unique to bispecific antibodies?"
-    )
+    session = await docs.aquery("What is PaperQA2?")
     print(session)
 
 
@@ -421,7 +418,7 @@ You can adjust this easily to use any model supported by `litellm`:
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(
         llm="gpt-4o-mini", summary_llm="gpt-4o-mini", paper_directory="my_papers"
     ),
@@ -437,7 +434,7 @@ from paperqa import Settings, ask
 from paperqa.settings import AgentSettings
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(
         llm="claude-3-5-sonnet-20240620",
         summary_llm="claude-3-5-sonnet-20240620",
@@ -455,7 +452,7 @@ from paperqa import Settings, ask
 from paperqa.settings import AgentSettings
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(
         llm="gemini/gemini-2.0-flash",
         summary_llm="gemini/gemini-2.0-flash",
@@ -491,7 +488,7 @@ local_llm_config = dict(
 )
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(
         llm="my-llm-model",
         llm_config=local_llm_config,
@@ -520,7 +517,7 @@ local_llm_config = {
 }
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(
         llm="ollama/llama3.2",
         llm_config=local_llm_config,
@@ -549,7 +546,7 @@ The simplest way to specify the embedding model is via `Settings.embedding`:
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(embedding="text-embedding-3-large"),
 )
 ```
@@ -606,7 +603,7 @@ and then prefix embedding model names with `st-`:
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(embedding="st-multi-qa-MiniLM-L6-cos-v1"),
 )
 ```
@@ -617,7 +614,7 @@ or with a hybrid model
 from paperqa import Settings, ask
 
 answer_response = ask(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=Settings(embedding="hybrid-st-multi-qa-MiniLM-L6-cos-v1"),
 )
 ```
@@ -634,7 +631,7 @@ settings.answer.answer_max_sources = 3
 settings.answer.k = 5
 
 await docs.aquery(
-    "What manufacturing challenges are unique to bispecific antibodies?",
+    "What is PaperQA2?",
     settings=settings,
 )
 ```
@@ -653,7 +650,9 @@ source_files = glob.glob("**/*.js")
 docs = Docs()
 for f in source_files:
     # this assumes the file names are unique in code
-    await docs.aadd(f, citation="File " + os.path.basename(f), docname=os.path.basename(f))
+    await docs.aadd(
+        f, citation="File " + os.path.basename(f), docname=os.path.basename(f)
+    )
 session = await docs.aquery("Where is the search bar in the header defined?")
 print(session)
 ```
@@ -726,11 +725,11 @@ async def amain(folder_of_papers: str | os.PathLike) -> None:
 
     # 2. Use the settings as many times as you want with ask
     answer_response_1 = await agent_query(
-        query="What is the best way to make a vaccine?",
+        query="What is a cool retrieval augmented generation technique?",
         settings=settings,
     )
     answer_response_2 = await agent_query(
-        query="What manufacturing challenges are unique to bispecific antibodies?",
+        query="What is PaperQA2?",
         settings=settings,
     )
 ```
@@ -863,10 +862,7 @@ docs = Docs()
 
 # add some docs...
 
-await docs.aquery(
-    "What manufacturing challenges are unique to bispecific antibodies?",
-    callbacks=[typewriter],
-)
+await docs.aquery("What is PaperQA2?", callbacks=[typewriter])
 ```
 
 ### Caching Embeddings
@@ -892,7 +888,7 @@ my_qa_prompt = (
 docs = Docs()
 settings = Settings()
 settings.prompts.qa = my_qa_prompt
-await docs.aquery("Are covid-19 vaccines effective?", settings=settings)
+await docs.aquery("What is PaperQA2?", settings=settings)
 ```
 
 ### Pre and Post Prompts

paperqa/agents/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import asyncio
 import logging
 import os
 from pathlib import Path
@@ -11,7 +12,7 @@
 from rich.logging import RichHandler
 
 from paperqa.settings import Settings, get_settings
-from paperqa.utils import get_loop, pqa_directory, setup_default_logs
+from paperqa.utils import pqa_directory, run_or_ensure, setup_default_logs
 from paperqa.version import __version__
 
 from .main import agent_query, index_search
@@ -98,25 +99,30 @@ def configure_cli_logging(verbosity: int | Settings = 0) -> None:
         print(f"PaperQA version: {__version__}")
 
 
-def ask(query: str | MultipleChoiceQuestion, settings: Settings) -> AnswerResponse:
+def ask(
+    query: str | MultipleChoiceQuestion, settings: Settings
+) -> AnswerResponse | asyncio.Task[AnswerResponse]:
     """Query PaperQA via an agent."""
     configure_cli_logging(settings)
-    return get_loop().run_until_complete(
-        agent_query(query, settings, agent_type=settings.agent.agent_type)
+    return run_or_ensure(
+        coro=agent_query(query, settings, agent_type=settings.agent.agent_type)
     )
 
 
 def search_query(
     query: str | MultipleChoiceQuestion,
     index_name: str,
     settings: Settings,
-) -> list[tuple[AnswerResponse, str] | tuple[Any, str]]:
+) -> (
+    list[tuple[AnswerResponse, str] | tuple[Any, str]]
+    | asyncio.Task[list[tuple[AnswerResponse, str] | tuple[Any, str]]]
+):
     """Search using a pre-built PaperQA index."""
     configure_cli_logging(settings)
     if index_name == "default":
         index_name = settings.get_index_name()
-    return get_loop().run_until_complete(
-        index_search(
+    return run_or_ensure(
+        coro=index_search(
             query if isinstance(query, str) else query.question_prompt,
             index_name=index_name,
             index_directory=settings.agent.index.index_directory,
@@ -128,7 +134,7 @@ def build_index(
     index_name: str | None = None,
     directory: str | os.PathLike | None = None,
     settings: Settings | None = None,
-) -> SearchIndex:
+) -> SearchIndex | asyncio.Task[SearchIndex]:
     """Build a PaperQA search index, this will also happen automatically upon using `ask`."""
     settings = get_settings(settings)
     if index_name == "default":
@@ -138,7 +144,7 @@ def build_index(
     configure_cli_logging(settings)
     if directory:
         settings.agent.index.paper_directory = directory
-    return get_loop().run_until_complete(get_directory_index(settings=settings))
+    return run_or_ensure(coro=get_directory_index(settings=settings))
 
 
 def save_settings(settings: Settings, settings_path: str | os.PathLike) -> None:

paperqa/utils.py

@@ -10,7 +10,7 @@
 import re
 import string
 import unicodedata
-from collections.abc import Collection, Iterable, Iterator
+from collections.abc import Awaitable, Collection, Iterable, Iterator
 from datetime import datetime
 from functools import reduce
 from http import HTTPStatus
@@ -215,6 +215,14 @@ def get_loop() -> asyncio.AbstractEventLoop:
     return loop
 
 
+def run_or_ensure(coro: Awaitable[T]) -> T | asyncio.Task[T]:
+    """Run a coroutine or convert to a future if an event loop is running."""
+    loop = get_loop()
+    if loop.is_running():  # In async contexts (e.g., Jupyter notebook), return a Task
+        return asyncio.ensure_future(coro)
+    return loop.run_until_complete(coro)
+
+
 def encode_id(value: str | bytes | UUID, maxsize: int | None = 16) -> str:
     """Encode a value (e.g. a DOI) optionally with a max length."""
     if isinstance(value, UUID):

tests/test_cli.py

@@ -7,15 +7,11 @@
 from tenacity import Retrying, retry_if_exception_type, stop_after_attempt
 
 from paperqa import Docs
+from paperqa.agents import ask, build_index, main, search_query
+from paperqa.agents.models import AnswerResponse
 from paperqa.settings import Settings
 from paperqa.utils import pqa_directory
 
-try:
-    from paperqa.agents import ask, build_index, main, search_query
-    from paperqa.agents.models import AnswerResponse
-except ImportError:
-    pytest.skip("agents module is not installed", allow_module_level=True)
-
 
 def test_can_modify_settings(capsys, stub_data_dir: Path) -> None:
     rel_path_home_to_stub_data = Path("~") / stub_data_dir.relative_to(Path.home())
@@ -58,13 +54,15 @@ def test_cli_ask(agent_index_dir: Path, stub_data_dir: Path) -> None:
     response = ask(
         "How can you use XAI for chemical property prediction?", settings=settings
     )
+    assert isinstance(response, AnswerResponse)
     assert response.session.formatted_answer
 
     search_result = search_query(
         " ".join(response.session.formatted_answer.split()),
         "answers",
         settings,
     )
+    assert isinstance(search_result, list)
     found_answer = search_result[0][0]
     assert isinstance(found_answer, AnswerResponse)
     assert found_answer.model_dump() == response.model_dump()
@@ -86,6 +84,7 @@ def test_cli_can_build_and_search_index(
         with attempt:
             build_index(index_name, stub_data_dir, settings)
     result = search_query("XAI", index_name, settings)
+    assert isinstance(result, list)
     assert len(result) == 1
     assert isinstance(result[0][0], Docs)
     assert all(d.startswith("Wellawatte") for d in result[0][0].docnames)