### Production Configuration Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates a typical configuration setup for production environments.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(
    llm_model="gpt-4-turbo",
    reranker_model="bi-encoder",
    retriever_type="full-text",
    n_retrieval=20,
    n_rerank=5,
    log_level="INFO",
    log_destination="gcs"
)
qa = ScholarQA(config=config)
result = qa.query("What are the ethical implications of AI?")
print(result)
```

--------------------------------

### Modal Configuration File Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/docs/MODAL.md

This is an example of the `.modal.toml` file created after setting up a Modal account and installing the package. It contains your authentication credentials.

```toml
[user]
token_id = "ak-*[...]*"
token_secret = "as-*[...]*"

active = true

```

--------------------------------

### Step-by-Step Pipeline Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates executing the ScholarQA pipeline step-by-step.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.pipeline_steps import step_select_quotes, step_clustering, generate_iterative_summary

qa = ScholarQA()
query = "What are the challenges in training large language models?"

# Step 1: Quote extraction
quotes = step_select_quotes(qa.config, query)

# Step 2: Clustering and planning
cluster_plan = step_clustering(qa.config, quotes)

# Step 3: Iterative summary
summary = generate_iterative_summary(qa.config, cluster_plan)
print(summary)
```

--------------------------------

### Example Configuration File Structure

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/00-index.md

A JSON structure representing a configuration file. It includes placeholders for logging setup and pipeline component configurations.

```json
{
  "logs": { /* logging setup */ },
  "run_config": { /* pipeline components */ }
}
```

--------------------------------

### Development Configuration Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows a configuration suitable for local development and testing.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(
    llm_model="gpt-3.5-turbo",
    reranker_model="cross-encoder",
    retriever_type="abstract",
    n_retrieval=10,
    n_rerank=3,
    log_level="DEBUG",
    log_destination="local"
)
qa = ScholarQA(config=config)
result = qa.query("How to build a simple chatbot?")
print(result)
```

--------------------------------

### Default Pipeline Configuration Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/04-configuration.md

A comprehensive example of the default configuration, including logging settings, retrieval service, reranker service, paper finder, and pipeline arguments.

```json
{
  "logs": {
    "log_dir": "logs",
    "log_level": "INFO",
    "llm_cache_dir": "llm_cache",
    "event_trace_loc": "scholarqa_traces",
    "tracing_mode": "local"
  },
  "run_config": {
    "retrieval_service": "public_api",
    "retriever_args": {
      "n_retrieval": 256,
      "n_keyword_srch": 20
    },
    "reranker_service": "modal",
    "reranker_args": {
      "app_name": "ai2-scholar-qa",
      "api_name": "inference_api",
      "batch_size": 256,
      "gen_options": {}
    },
    "paper_finder_args": {
      "n_rerank": 50,
      "context_threshold": 0.0
    },
    "pipeline_args": {
      "validate": true,
      "llm": "anthropic/claude-3-5-sonnet-20241022",
      "decomposer_llm": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```

--------------------------------

### Custom Configuration Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to initialize ScholarQA with custom configuration settings.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(llm_model="gpt-4", reranker_model="cross-encoder")
qa = ScholarQA(config=config)
result = qa.query("What are the applications of transformers?")
print(result)
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/docs/DOCKER.md

Run this command to start the application locally for development. It builds the necessary Docker images and launches the services. The application will be accessible at http://localhost:8080.

```bash
docker compose up --build
```

--------------------------------

### Example: Configuration - Setting up RunConfig

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to set up run-specific configurations using `RunConfig`. This might include parameters for a particular execution or experiment.

```python
from ai2_scholarqa_lib.config import RunConfig

run_config = RunConfig(output_dir="./results/run_001", max_iterations=10)
print(f"Output Directory: {run_config.output_dir}")
```

--------------------------------

### Cost Monitoring Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to enable and access cost monitoring information.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(enable_cost_monitoring=True)
qa = ScholarQA(config=config)
result = qa.query("Analyze the economic impact of AI.")
print(result)

# Access cost details
print(f"Total cost: {qa.cost_tracker.total_cost:.4f}")
print(f"Token usage: {qa.cost_tracker.token_usage}")
```

--------------------------------

### Example: Configuration - Setting up AppConfig

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to load and configure application settings using `AppConfig`. This typically involves providing a path to a configuration file.

```python
from ai2_scholarqa_lib.config import AppConfig

config = AppConfig(config_path="./config/app_settings.yaml")
print(f"LLM Model: {config.llm_model}")
```

--------------------------------

### Example: API Usage - Getting Paper Details

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

This example demonstrates fetching detailed information for a specific paper using its ID via the library's API.

```python
# Assuming ai2_scholarqa_lib is installed and configured
from ai2_scholarqa_lib.api import get_paper_details

paper_id = "2108009"
details = get_paper_details(paper_id)
print(f"Title: {details['title']}")
print(f"Abstract: {details['abstract'][:100]}...")
```

--------------------------------

### Simple Library Usage Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates basic usage of the ScholarQA library for a simple query.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA

qa = ScholarQA()
result = qa.query("What is the main idea of the paper 'Attention Is All You Need'?")
print(result)
```

--------------------------------

### Install all dependencies for CrossEncoderScores

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Use this command to install all necessary dependencies, including torch and transformers, required for CrossEncoderScores to function correctly.

```bash
pip install 'ai2-scholar-qa[all]'
```

--------------------------------

### Example: Initializing Logging Settings

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to initialize logging settings for the library using `init_settings`. This is often a first step in using the library for tasks that require logging.

```python
from ai2_scholarqa_lib.logging import init_settings

init_settings(log_level="INFO", task_id="my_task_123")
```

--------------------------------

### Run the API Server

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/README.md

Instructions for starting the ScholarQA API server using Docker Compose. It also shows the endpoint for POST requests.

```bash
docker compose up
# POST to http://localhost:8000/api/query_corpusqa
```

--------------------------------

### Example: API Usage - Querying Papers

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

This example shows how to use the library's API to search for papers based on a query string. It retrieves metadata for matching papers.

```python
# Assuming ai2_scholarqa_lib is installed and configured
from ai2_scholarqa_lib.api import search_papers

results = search_papers(query="natural language processing", limit=5)
for paper in results:
    print(f"- {paper['title']} ({paper['year']})")
```

--------------------------------

### Event Trace Analysis Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to enable and analyze event tracing for debugging.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(enable_event_tracing=True, event_trace_file="trace.jsonl")
qa = ScholarQA(config=config)
result = qa.query("What are the latest advancements in robotics?")
print(result)

# After execution, analyze trace.jsonl for detailed event information.
```

--------------------------------

### Example: Debugging - Inspecting LLM Cache

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to set up and potentially inspect the LLM cache using `setup_llm_cache`. Caching can significantly speed up repeated LLM calls.

```python
from ai2_scholarqa_lib.llm import setup_llm_cache

setup_llm_cache(cache_dir="./.llm_cache")
# You can then inspect the contents of the './.llm_cache' directory
# to see cached responses.
```

--------------------------------

### Example: Basic LLM Completion

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates a basic call to the `llm_completion` function for generating text. Ensure the LLM is set up before calling this function.

```python
from ai2_scholarqa_lib.llm import llm_completion

response = llm_completion("What is the capital of France?")
print(response)
```

--------------------------------

### Install Python Dependency

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/docs/DOCKER.md

Install a new dependency into the Python environment within the API container. This command should be run after entering the container's shell.

```bash
python -m pip install <dependency>
```

--------------------------------

### Fallback LLM Retry Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates configuring a fallback LLM in case the primary LLM fails.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(
    llm_model="gpt-4",
    fallback_llm_model="gpt-3.5-turbo",
    llm_retries=3
)
qa = ScholarQA(config=config)
result = qa.query("What is the future of renewable energy?")
print(result)
```

--------------------------------

### Example: Batch LLM Completions

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to perform multiple LLM completions in a single batch request using `batch_llm_completion`. This can be more efficient for multiple queries.

```python
from ai2_scholarqa_lib.llm import batch_llm_completion

queries = [
    "What is the capital of Spain?",
    "What is the largest planet in our solar system?"
]
responses = batch_llm_completion(queries)
for query, response in zip(queries, responses):
    print(f"Q: {query}\nA: {response}")
```

--------------------------------

### GET /

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/03-endpoints.md

Root endpoint for the API, typically returning a welcome message.

```APIDOC
## GET /

### Description
Root endpoint.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **message** (string) - A welcome message.
- **root_path** (string) - The root path of the API.

### Response Example
```json
{
  "message": "Hello World",
  "root_path": "/api"
}
```
```

--------------------------------

### Install AI2 ScholarQA Python Package

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/README.md

Installs the ai2-scholar-qa package and optional dependencies for sentence transformer models. Use this to set up the library for local development or use.

```bash
conda create -n scholarqa python=3.11.3
conda activate scholarqa
pip install ai2-scholar-qa

#to use sentence transformer models as re-ranker
pip install 'ai2-scholar-qa[all]'
```

--------------------------------

### Python Method Signature Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/00-index.md

Demonstrates the signature for the 'answer_query' method, including parameter types, default values, and the return type.

```python
def answer_query(self, query: str, inline_tags: bool = True) -> Dict[str, Any]

...
```

--------------------------------

### Custom Retriever Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to integrate a custom retriever with ScholarQA.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.retrievers import AbstractRetriever

class CustomRetriever(AbstractRetriever):
    def retrieve(self, query: str, n_retrieval: int) -> list[str]:
        # Custom retrieval logic here
        return ["doc1_id", "doc2_id"]

qa = ScholarQA()
qa.retriever = CustomRetriever()
result = qa.query("What is the impact of climate change?")
print(result)
```

--------------------------------

### Step-by-Step ScholarQA Pipeline

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/09-examples.md

This example demonstrates the full ScholarQA pipeline, from query preprocessing to iterative summary generation. It shows how to set up retrievers, rerankers, and the main ScholarQA object, then sequentially executes each step of the pipeline.

```python
from scholarqa import ScholarQA, FullTextRetriever, PaperFinderWithReranker
from scholarqa.rag.reranker.reranker_base import CrossEncoderScores
from scholarqa.llms.constants import CLAUDE_37_SONNET
from scholarqa.llms.prompts import SYSTEM_PROMPT_QUOTE_PER_PAPER, SYSTEM_PROMPT_QUOTE_CLUSTER, PROMPT_ASSEMBLE_SUMMARY
from scholarqa.utils import NUMERIC_META_FIELDS, CATEGORICAL_META_FIELDS

# Setup
retriever = FullTextRetriever(n_retrieval=256, n_keyword_srch=20)
reranker = CrossEncoderScores(model_name_or_path="mixedbread-ai/mxbai-rerank-large-v1")
paper_finder = PaperFinderWithReranker(retriever, reranker, n_rerank=50)
scholar_qa = ScholarQA(paper_finder=paper_finder, llm_model=CLAUDE_37_SONNET)

query = "What are the societal impacts of artificial intelligence?"

# Step 0: Decompose query
llm_processed_query = scholar_qa.preprocess_query(query)
print(f"Rewritten query: {llm_processed_query.result.rewritten_query}")
print(f"Keyword query: {llm_processed_query.result.keyword_query}")

# Step 1: Retrieve papers
snippet_results, keyword_results = scholar_qa.find_relevant_papers(llm_processed_query.result)
retrieved_candidates = snippet_results + keyword_results
print(f"Retrieved {len(retrieved_candidates)} candidate passages")

# Step 2: Rerank and aggregate
keyword_metadata = [
    {k: v for k, v in paper.items() if k == "corpus_id" or k in NUMERIC_META_FIELDS or k in CATEGORICAL_META_FIELDS}
    for paper in keyword_results
]
reranked_df, paper_metadata = scholar_qa.rerank_and_aggregate(
    query, retrieved_candidates,
    filter_paper_metadata={str(paper["corpus_id"]): paper for paper in keyword_metadata}
)
print(f"Reranked to {len(reranked_df)} papers")

# Step 3: Quote extraction
per_paper_quotes = scholar_qa.step_select_quotes(query, reranked_df, sys_prompt=SYSTEM_PROMPT_QUOTE_PER_PAPER)
print(f"Extracted quotes from {len(per_paper_quotes.result)} papers")

# Step 4: Clustering
cluster_result = scholar_qa.step_clustering(query, per_paper_quotes.result, sys_prompt=SYSTEM_PROMPT_QUOTE_CLUSTER)
print(f"Generated {len(cluster_result.result['dimensions'])} sections")
plan_json = {f'{dim["name"]} ({dim["format"]})': dim["quotes"] for dim in cluster_result.result["dimensions"]}

# Step 5: Extend quotes with citations
per_paper_summaries_extd, quotes_metadata = scholar_qa.extract_quote_citations(
    reranked_df, per_paper_quotes.result, plan_json, paper_metadata
)

# Step 6: Iterative generation
sections = []
for section_text in scholar_qa.step_gen_iterative_summary(
    query, per_paper_summaries_extd, plan_json, sys_prompt=PROMPT_ASSEMBLE_SUMMARY
):
    sections.append(section_text)
    print(f"Generated section: {len(section_text)} chars")

print(f"\nTotal sections: {len(sections)}")
```

--------------------------------

### ModalReranker Setup Requirements

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Sets environment variables for Modal authentication token and secret.

```bash
export MODAL_TOKEN=<your-modal-token>
export MODAL_TOKEN_SECRET=<your-modal-secret>
```

--------------------------------

### Sample Usage of ScholarQA Class

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/README.md

Demonstrates how to initialize and use the ScholarQA class for answering queries. This example shows setting up a retriever, reranker, and the main ScholarQA pipeline.

```python
from scholarqa.rag.reranker.reranker_base import CrossEncoderScores
from scholarqa.rag.reranker.modal_engine import ModalReranker
from scholarqa.rag.retrieval import PaperFinderWithReranker
from scholarqa.rag.retriever_base import FullTextRetriever
from scholarqa import ScholarQA
from scholarqa.llms.constants import CLAUDE_37_SONNET

#Retrieval class/steps
retriever = FullTextRetriever(n_retrieval=256, n_keyword_srch=20) #full text and keyword search
reranker = CrossEncoderScores(model_name_or_path="mixedbread-ai/mxbai-rerank-large-v1") #sentence transformer


#Reranker if deployed on Modal, modal_app_name and modal_api_name are modal specific arguments.
#Please refer https://github.com/allenai/ai2-scholarqa-lib/blob/aps/readme_fixes/docs/MODAL.md for more info 
reranker = ModalReranker(app_name='<modal_app_name>', api_name='<modal_api_name>', batch_size=256, gen_options=dict())

#wraps around the retriever with `retrieve_passages()` and `retrieve_additional_papers()`, and reranker with rerank()
#any modifications to the retrieval output can be made here
paper_finder =  PaperFinderWithReranker(retriever, reranker, n_rerank=50, context_threshold=0.0)

#For wrapper class with MultiStepQAPipeline integrated
scholar_qa = ScholarQA(paper_finder=paper_finder, llm_model=CLAUDE_37_SONNET) #llm_model can be any litellm model
print(scholar_qa.answer_query("Which is the 9th planet in our solar system?"))
```

--------------------------------

### Optional Configuration Environment Variables

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/04-configuration.md

Configure optional settings for storage, deployment, tracing, and application behavior. Ensure paths and values are correct for your setup.

```bash
# GCS storage for event traces
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

# Modal deployment
export MODAL_TOKEN=<token>
export MODAL_TOKEN_SECRET=<secret>

# LangSmith tracing
export LANGCHAIN_API_KEY=<api-key>
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
export LANGCHAIN_PROJECT=<project-name>

# Application settings
export CONFIG_PATH=run_configs/default.json
export LOG_LEVEL=INFO
export SQA_MODE=default  # or "lite"
export PYTHONUNBUFFERED=1  # For Docker
```

--------------------------------

### Error Handling Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to handle potential errors during query processing.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.exceptions import ScholarQAError

try:
    qa = ScholarQA()
    result = qa.query("An invalid query that might cause an error.")
    print(result)
except ScholarQAError as e:
    print(f"An error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

--------------------------------

### Example Usage of ModalReranker

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Demonstrates how to instantiate and use the ModalReranker to obtain scores for a given query and passages.

```python
reranker = ModalReranker(
    app_name="ai2-scholar-qa",
    api_name="inference_api",
    batch_size=256
)
scores = reranker.get_scores("climate change", passages)
```

--------------------------------

### Example Usage of LocalStateMgrClient for LLM Cost Reporting

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/07-state-management.md

Demonstrates initializing the `LocalStateMgrClient`, setting up a task, and then reporting LLM usage with completion results and cost arguments. This is useful for tracking expenses during local development.

```python
state_mgr = LocalStateMgrClient(logs_dir="logs")
state_mgr.init_task("task-123", tool_request)

# Later, report costs from a step
completion_results = [
    CompletionResult(content="...", model="claude-3-5-sonnet", cost=0.15, ...)
]
total_cost, tokens = state_mgr.report_llm_usage(
    completion_results,
    CostReportingArgs(
        task_id="task-123",
        user_id="user-456",
        msg_id="task-123",
        description="Step 1: Quote extraction",
        model="claude-3-5-sonnet"
    )
)
print(f"Total cost: ${total_cost}")
```

--------------------------------

### Docker Compose .env File Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/04-configuration.md

Provide API keys and secrets in a .env file, which is referenced by docker-compose.yaml. Keep this file secure.

```bash
S2_API_KEY=your-s2-api-key
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key
MODAL_TOKEN=your-modal-token
MODAL_TOKEN_SECRET=your-modal-secret
```

--------------------------------

### Reranker Service Configuration

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Example JSON configuration for specifying the reranker service and its arguments.

```json
{
  "reranker_service": "crossencoder",
  "reranker_args": {
    "model_name_or_path": "mixedbread-ai/mxbai-rerank-large-v1"
  }
}
```

--------------------------------

### Async API Polling Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Demonstrates polling the asynchronous API for task status using bash.

```bash
TASK_ID="your_task_id"

while true;
  do
    curl -X GET "http://localhost:8000/status?task_id=$TASK_ID"
    sleep 5
  done
```

--------------------------------

### Python Class Constructor Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/00-index.md

Illustrates the constructor signature for a Python class within the scholarqa library. It shows parameter types, requirements, defaults, and descriptions.

```python
def __init__(
    self,
    paper_finder: PaperFinder,
    task_id: str = None,
    ...
)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| paper_finder | PaperFinder | Yes | — | Instance handling... |
```

--------------------------------

### ScholarQA with Custom Configuration for Speed

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/09-examples.md

This example demonstrates how to configure ScholarQA for faster execution by reducing retrieval parameters and disabling reranking. It also shows how to use a cheaper LLM for cost savings.

```python
from scholarqa import ScholarQA, FullTextRetriever, PaperFinder
from scholarqa.llms.constants import CLAUDE_35_SONNET

# Lighter retrieval for speed
retriever = FullTextRetriever(n_retrieval=128, n_keyword_srch=10)

# No reranking (just filter by relevance)
paper_finder = PaperFinder(
    retriever,
    n_rerank=-1,  # Keep all papers
    context_threshold=0.3  # Filter low-relevance ones
)

# Cheaper LLM
scholar_qa = ScholarQA(
    paper_finder=paper_finder,
    llm_model="openai/gpt-4o-mini"
)

result = scholar_qa.answer_query("What is artificial intelligence?")
print(f"Fast execution cost: ${result['cost']}")
```

--------------------------------

### Custom LLM Selection Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates selecting a specific LLM for use with ScholarQA.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.settings import AppConfig

config = AppConfig(llm_model="claude-3-opus-20240229")
qa = ScholarQA(config=config)
result = qa.query("Summarize the key findings of recent AI research.")
print(result)
```

--------------------------------

### Example: Advanced - Token Usage Tracking

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates how `TokenUsage` can be used to track token counts for LLM interactions. This is crucial for managing costs and understanding API limits.

```python
from ai2_scholarqa_lib.cost import TokenUsage

usage = TokenUsage(prompt_tokens=100, completion_tokens=20)
print(f"Total tokens: {usage.prompt_tokens + usage.completion_tokens}")
```

--------------------------------

### Input Data Structure Examples

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/06-generation-pipeline.md

Illustrates the expected structure for per_paper_summaries_extd and plan inputs. per_paper_summaries_extd contains quotes and inline citations, while plan maps section names to quote indices.

```python
per_paper_summaries_extd = {
    "[ref_str1]": {
        "quote": "Climate change affects yields…",
        "inline_citations": {
            "[another_paper]": "Abstract of another paper…"
        }
    },
    # …
}

plan = {
    "Overview (synthesis)": [0, 2, 5],
    "Regional Effects (list)": [1, 3, 7]
}
```

--------------------------------

### Example: Query Decomposition

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates how to decompose a complex query into smaller, manageable parts using the `decompose_query` function. This is useful for planning multi-step question answering.

```python
from ai2_scholarqa_lib.query import decompose_query

complex_query = "What were the main findings of the paper on transformer models published in 2017?"
decomposed = decompose_query(complex_query)
print(decomposed)
```

--------------------------------

### Combination Request (Mentioned Papers + Search)

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/EDIT_WORKFLOW.md

This example demonstrates how to combine adding specific mentioned papers with a search for related topics. Both 'mentioned_papers' and a descriptive 'edit_instruction' are used.

```json
{
    "edit_existing": true,
    "thread_id": "abc-123",
    "edit_instruction": "Add this paper and others like it about attention mechanisms",
    "mentioned_papers": [123456789]
}
```

--------------------------------

### Example: Parsing Citation Key

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Shows how to parse a citation key into a structured format using `parse_citation_key`. Useful for normalizing citation references.

```python
from ai2_scholarqa_lib.utilities import parse_citation_key

key = "vaswani2017attention"
parsed = parse_citation_key(key)
print(parsed)
```

--------------------------------

### Example Usage of step_clustering

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/06-generation-pipeline.md

Demonstrates how to call the `step_clustering` function and access its output. It shows how to print the report title and iterate through the generated dimensions to display their names, formats, and the number of quotes assigned.

```python
cluster_result, completion = pipeline.step_clustering(
    query="What are the impacts of climate change on agriculture?",
    per_paper_summaries=per_paper_quotes,
    sys_prompt=SYSTEM_PROMPT_QUOTE_CLUSTER
)

print(cluster_result["report_title"])  # "Climate Change and Agricultural Systems"
for dim in cluster_result["dimensions"]:
    print(f"- {dim['name']} ({dim['format']}): {len(dim['quotes'])} quotes")
```

--------------------------------

### Event Trace File Structure Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/07-state-management.md

A JSON representation of a complete event trace, detailing task information, retrieval, reranking, step costs, token usage, and total cost/tokens.

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user-123",
  "query": "What is climate change?",
  "n_retrieval": 256,
  "n_rerank": 50,
  "retrieval": {
    "full_text_snippets": 256,
    "keyword_papers": 20,
    "total_cost": 0.02
  },
  "reranking": {
    "papers_after_rerank": 50,
    "cost": 0.05
  },
  "step1_quotes": {
    "papers_with_quotes": 45,
    "cost": 0.15,
    "tokens": {
      "input": 45000,
      "output": 2000,
      "total": 47000
    }
  },
  "step2_clustering": {
    "dimensions": 5,
    "cost": 0.08,
    "tokens": {"input": 10000, "output": 500, "total": 10500}
  },
  "step3_generation": {
    "sections": 5,
    "cost": 0.20,
    "tokens": {"input": 25000, "output": 5000, "total": 30000}
  },
  "total_cost": 0.50,
  "total_tokens": 87500,
  "timestamp": 1692374400.123
}
```

--------------------------------

### Example Usage of Iterative Summary Generation

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/06-generation-pipeline.md

Demonstrates how to use the generate_iterative_summary function within a loop to collect generated sections. It shows how to iterate over the yielded results and append the content.

```python
sections = []
for section_result in pipeline.generate_iterative_summary(
    query="What are the impacts of climate change on agriculture?",
    per_paper_summaries_extd=extended_quotes,
    plan=plan_json,
    sys_prompt=PROMPT_ASSEMBLE_SUMMARY
):
    sections.append(section_result.content)
    print(f"Generated section: {len(section_result.content)} chars")

# sections now contains generated text for each dimension
```

--------------------------------

### Running ScholarQA API Server

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/00-index.md

Provides commands to start the ScholarQA asynchronous API server using Docker Compose or directly with uvicorn. The API supports POST requests to `/api/query_corpusqa` and allows polling for task results.

```bash
docker compose up
# Or:
uvicorn scholarqa.app:create_app --host 0.0.0.0 --port 8000
```

--------------------------------

### Backend Question Answering Pipeline

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/README.md

Demonstrates the full question-answering pipeline using ScholarQA, from query preprocessing to iterative summary generation. Requires setup of ScholarQA with a paper finder and multi-step pipeline.

```python
from scholarqa import ScholarQA
from scholarqa.rag.multi_step_qa_pipeline import MultiStepQAPipeline
from scholarqa.llms.constants import CLAUDE_37_SONNET
from scholarqa.llms.prompts import SYSTEM_PROMPT_QUOTE_PER_PAPER, SYSTEM_PROMPT_QUOTE_CLUSTER, PROMPT_ASSEMBLE_SUMMARY
from scholarqa.utils import NUMERIC_META_FIELDS, CATEGORICAL_META_FIELDS

# Custom MultiStepQAPipeline class/steps with llm_model asa any litellm supported model
mqa_pipeline = MultiStepQAPipeline(llm_model=CLAUDE_37_SONNET)

query = "Which is the 9th planet in our solar system?"

scholar_qa = ScholarQA(paper_finder=paper_finder, multi_step_pipeline=mqa_pipeline, llm_model=CLAUDE_37_SONNET)

# Decompose the query to get filters like year, venue, fos, citations, etc along with
# a re-written version of the query and a query suitable for keyword search.
llm_processed_query = scholar_qa.preprocess_query(query)

# Paper finder step - retrieve relevant paper passages from semantic scholar index and api
full_text_src, keyword_srch_res = scholar_qa.find_relevant_papers(llm_processed_query.result)
retrieved_candidates = full_text_src + keyword_srch_res

# Rerank the retrieved candidates based on the query with a cross encoder
# keyword search results are returned with associated metadata, metadata is retrieved separately for full text serach results
keyword_srch_metadata = [
    {k: v for k, v in paper.items() if k == "corpus_id" or k in NUMERIC_META_FIELDS or k in CATEGORICAL_META_FIELDS}
    for paper in keyword_srch_res]
reranked_df, paper_metadata = scholar_qa.rerank_and_aggregate(query, retrieved_candidates,
                                                              filter_paper_metadata={str(paper["corpus_id"]): paper for
                                                                                     paper in
                                                                                     keyword_srch_metadata})
# Step 1 - quote extraction
per_paper_quotes = scholar_qa.step_select_quotes(query, reranked_df, sys_prompt=SYSTEM_PROMPT_QUOTE_PER_PAPER)

# step 2: outline planning and clustering
cluster_json = scholar_qa.step_clustering(query, per_paper_quotes.result, sys_prompt=SYSTEM_PROMPT_QUOTE_CLUSTER)

# Changing to expected format in the summary generation prompt
plan_json = {f'{dim["name"]} ({dim["format"]})': dim["quotes"] for dim in cluster_json.result["dimensions"]}

# step 2.1: extend the clustered snippets in plan json with their inline citations
per_paper_summaries_extd = scholar_qa.extract_quote_citations(reranked_df, per_paper_quotes.result, plan_json,
                                                              paper_metadata)

# step 3: generating output as per the outline
answer = list(scholar_qa.step_gen_iterative_summary(query, per_paper_summaries_extd, plan_json,
                                                    sys_prompt=PROMPT_ASSEMBLE_SUMMARY))

```

--------------------------------

### Example Usage of CrossEncoderScores

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Demonstrates how to initialize and use the CrossEncoderScores reranker to get relevance scores for passages given a query.

```python
from scholarqa.rag.reranker.reranker_base import CrossEncoderScores

reranker = CrossEncoderScores(model_name_or_path="mixedbread-ai/mxbai-rerank-large-v1")
query = "climate change agriculture"
passages = [
    "Climate change impacts crop yields...",
    "The history of farming in ancient Rome...",
    "Temperature shifts affect plant growth...",
]
scores = reranker.get_scores(query, passages)
print(scores)  # [0.85, 0.12, 0.92]
```

--------------------------------

### Example: Getting Reference Author String

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates how to format an author string from a list of authors using `get_ref_author_str`. Useful for consistent citation formatting.

```python
from ai2_scholarqa_lib.utilities import get_ref_author_str

authors = [{"name": "Ashish Vaswani"}, {"name": "Noam Shazeer"}]
author_str = get_ref_author_str(authors)
print(author_str)
```

--------------------------------

### Install ai2-scholar-qa Package

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/00-index.md

Install the core ai2-scholar-qa package using pip. For full functionality including sentence transformer rerankers, install with the 'all' extra.

```bash
pip install ai2-scholar-qa

# For sentence transformer rerankers:
pip install 'ai2-scholar-qa[all]'
```

--------------------------------

### Query Semantic Scholar API (GET)

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/08-utilities-and-helpers.md

Queries the Semantic Scholar API using the GET method. Suitable for retrieving data like search results.

```python
# Snippet search
results = query_s2_api(
    end_pt="snippet/search",
    params={
        "query": "climate change",
        "limit": 10,
        "fields": "snippet.text,paper.title"
    },
    method="get"
)
```

--------------------------------

### Custom Reranker Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates integrating a custom reranker with ScholarQA.

```python
from ai2_scholarqa_lib.scholarqa import ScholarQA
from ai2_scholarqa_lib.rerankers import AbstractReranker

class CustomReranker(AbstractReranker):
    def rerank(self, query: str, documents: list[str]) -> list[tuple[str, float]]:
        # Custom reranking logic here
        return [(doc, 0.5) for doc in documents]

qa = ScholarQA()
qa.reranker = CustomReranker()
result = qa.query("How does machine learning apply to drug discovery?")
print(result)
```

--------------------------------

### GET /health

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/03-endpoints.md

Health check endpoint to verify the service is running.

```APIDOC
## GET /health

### Description
Health check endpoint.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (204)
- **Body**: Empty
```

--------------------------------

### setup_llm_cache

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/08-utilities-and-helpers.md

Initializes the litellm caching backend, supporting 'disk', 'redis', and 's3' cache types.

```APIDOC
## setup_llm_cache

### Description
Initializes the litellm caching backend. This function allows you to configure where and how LLM responses are cached to improve performance and reduce costs.

### Method
`setup_llm_cache`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **cache_type** (str) - Optional - The type of cache to use. Supported types are "disk", "redis", and "s3". Defaults to "s3".
- **disk_cache_dir** (str) - Optional - The directory path for disk-based caching. Required if `cache_type` is "disk".
- **redis_url** (str) - Optional - The connection URL for a Redis cache. Required if `cache_type` is "redis".
- **cache_args** (dict) - Optional - Additional arguments to pass to the cache backend.

### Request Example
```python
from scholarqa.llms.litellm_helper import setup_llm_cache

# Disk cache setup
setup_llm_cache(cache_type="disk", disk_cache_dir="./llm_cache")

# Redis cache setup
setup_llm_cache(cache_type="redis", redis_url="redis://localhost:6379")
```

### Response
#### Success Response
None. This function configures the cache and does not return a value.

#### Response Example
N/A
```

--------------------------------

### init_settings

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/08-utilities-and-helpers.md

Initializes the logging system and optionally configures litellm caching. It returns a TaskIdAwareLogFormatter instance.

```APIDOC
## init_settings

### Description
Initializes logging and litellm caching. This function sets up the necessary configurations for logging, including the log directory and level, and prepares the cache directory for litellm.

### Function Signature
`scholarqa.utils.init_settings(logs_dir: str, log_level: str = "INFO", litellm_cache_dir: str = "litellm_cache") -> TaskIdAwareLogFormatter`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

#### Function Parameters
- **logs_dir** (str) - Required - Root directory for logs.
- **log_level** (str) - Optional - Logging level. Defaults to "INFO".
- **litellm_cache_dir** (str) - Optional - Cache subdirectory for litellm. Defaults to "litellm_cache".

### Returns
- **TaskIdAwareLogFormatter** - A formatter instance configured for task ID awareness.

### Example
```python
from scholarqa.utils import init_settings

formatter = init_settings(
    logs_dir="./logs",
    log_level="INFO",
    litellm_cache_dir="llm_cache"
)
```
```

--------------------------------

### Initialize CostAwareLLMCaller

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/07-state-management.md

Instantiate the CostAwareLLMCaller with a state manager for cost reporting.

```python
from scholarqa.llms.litellm_helper import CostAwareLLMCaller

# Assuming state_mgr is an instance of AbsStateMgrClient
llm_caller = CostAwareLLMCaller(state_mgr)
```

--------------------------------

### Initialize Settings with Logging and Caching

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/08-utilities-and-helpers.md

Initializes logging and LiteLLM caching. This function sets up the logging environment and returns a TaskIdAwareLogFormatter instance.

```python
from scholarqa.utils import init_settings

formatter = init_settings(
    logs_dir="./logs",
    log_level="INFO",
    litellm_cache_dir="llm_cache"
)
```

--------------------------------

### Initialize MultiStepQAPipeline

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/06-generation-pipeline.md

Instantiate the MultiStepQAPipeline with primary and fallback LLM models, and configure batch workers and additional LLM parameters.

```python
from scholarqa.rag.multi_step_qa_pipeline import MultiStepQAPipeline
from scholarqa.llms.constants import CLAUDE_37_SONNET

pipeline = MultiStepQAPipeline(
    llm_model=CLAUDE_37_SONNET,
    fallback_llm="openai/gpt-5-chat-latest",
    batch_workers=20,
    max_tokens=16384
)
```

--------------------------------

### MultiStepQAPipeline Constructor

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/01-core-classes.md

Initializes the MultiStepQAPipeline with primary and fallback LLM models, and configuration for batch processing. Use this to set up a pipeline for complex question answering tasks involving multiple steps.

```python
def __init__(
    self,
    llm_model: str,
    fallback_llm: str = GPT_4o,
    batch_workers: int = 20,
    **llm_kwargs
)
```

--------------------------------

### Review Cost Report Example

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/07-state-management.md

After task completion, a cost report summarizes the expenses for each step and the total cost.

```text
Step 0: Query decomposition - $0.001 (1000 tokens)
Step 1: Quote extraction - $0.15 (47000 tokens)
Step 2: Clustering - $0.08 (10500 tokens)
Step 3: Generation - $0.20 (30000 tokens)
Table generation - $0.05 (2000 tokens)
---
Total: $0.49 (90500 tokens)
```

--------------------------------

### Basic ScholarQA Query

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/09-examples.md

This snippet shows the fundamental setup for ScholarQA, including initializing the retriever, reranker, paper finder, and the main ScholarQA class. It then answers a query and prints key results like the report title, cost, and section summaries.

```python
from scholarqa import ScholarQA, FullTextRetriever, PaperFinderWithReranker
from scholarqa.rag.reranker.reranker_base import CrossEncoderScores
from scholarqa.llms.constants import CLAUDE_37_SONNET

# Initialize components
retriever = FullTextRetriever(n_retrieval=256, n_keyword_srch=20)
reranker = CrossEncoderScores(model_name_or_path="mixedbread-ai/mxbai-rerank-large-v1")
paper_finder = PaperFinderWithReranker(retriever, reranker, n_rerank=50, context_threshold=0.0)

# Create ScholarQA instance
scholar_qa = ScholarQA(paper_finder=paper_finder, llm_model=CLAUDE_37_SONNET)

# Answer a query
result = scholar_qa.answer_query("What is the impact of climate change on agriculture?")

# Access results
print(f"Report title: {result['report_title']}")
print(f"Total cost: ${result['cost']}")
print(f"Sections: {len(result['sections'])}")

for section in result['sections']:
    print(f"\n## {section['title']}")
    print(f"TLDR: {section['tldr']}")
    print(f"Citations: {len(section['citations'])}")
```

--------------------------------

### Semantic Scholar API - Snippet Search Endpoint

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

GET request for full-text snippet search. Limited by S2_API_KEY quota.

```http
GET /graph/v1/snippet/search
Query: Full text search across paper corpus
Rate: Limited by S2_API_KEY quota
```

--------------------------------

### Configure CrossEncoder Reranker (Local)

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/04-configuration.md

Enables local reranking using a specified HuggingFace CrossEncoder model. Requires the `[all]` extra to be installed.

```json
{
  "run_config": {
    "reranker_service": "crossencoder",
    "reranker_args": {
      "model_name_or_path": "mixedbread-ai/mxbai-rerank-large-v1"
    }
  }
}
```

--------------------------------

### Simple ScholarQA Library Usage

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/00-index.md

Demonstrates basic initialization and usage of the ScholarQA library for answering a scientific question. Ensure necessary components like FullTextRetriever and PaperFinderWithReranker are imported.

```python
from scholarqa import ScholarQA, FullTextRetriever, PaperFinderWithReranker
from scholarqa.rag.reranker.reranker_base import CrossEncoderScores

retriever = FullTextRetriever(n_retrieval=256, n_keyword_srch=20)
reranker = CrossEncoderScores(model_name_or_path="mixedbread-ai/mxbai-rerank-large-v1")
paper_finder = PaperFinderWithReranker(retriever, reranker, n_rerank=50)
scholar_qa = ScholarQA(paper_finder=paper_finder)

result = scholar_qa.answer_query("Your scientific question here")
print(result['report_title'])
```

--------------------------------

### Semantic Scholar API - Paper Search Endpoint

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

GET request for keyword search on paper titles and abstracts. Limited by S2_API_KEY quota.

```http
GET /graph/v1/paper/search
Query: Keyword search on titles/abstracts
Rate: Limited by S2_API_KEY quota
```

--------------------------------

### ModalReranker get_scores Method

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Calls a remote Modal function to get reranking scores for a query and a list of documents, handling batching internally.

```python
def get_scores(self, query: str, documents: List[str]) -> List[float]
```

--------------------------------

### Update Python Requirements

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/docs/DOCKER.md

Freeze the current Python dependencies into the requirements.txt file. This command should be run after installing new dependencies within the API container.

```bash
python -m pip freeze -l > requirements.txt
```

--------------------------------

### Example: Debugging - TaskIdAwareLogFormatter

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/MANIFEST.txt

Illustrates the use of `TaskIdAwareLogFormatter` for including task IDs in log messages. This is helpful for tracking requests across distributed systems.

```python
import logging
from ai2_scholarqa_lib.logging import TaskIdAwareLogFormatter

formatter = TaskIdAwareLogFormatter()
# Configure your logger to use this formatter
# logger = logging.getLogger('my_app')
# logger.handlers[0].setFormatter(formatter)
# logger.info('Processing item X', extra={'task_id': 'task_abc'})
```

--------------------------------

### ModalReranker

Source: https://github.com/allenai/ai2-scholarqa-lib.git/blob/main/_autodocs/05-retrieval-reranking.md

Reranker deployed on Modal serverless platform. It calls a Modal function remotely to get reranking scores for documents. Supports batching for efficiency.

```APIDOC
## ModalReranker

### Description
Reranker deployed on Modal serverless platform. Calls Modal function remotely via modal.Function.remote(). Divides documents into batches of batch_size.

### Constructor
```python
def __init__(self,
    app_name: str,
    api_name: str,
    batch_size: int = 32,
    gen_options: Dict[str, Any] = None
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| app_name | str | — | Modal app name (e.g., "ai2-scholar-qa") |
| api_name | str | — | Modal API endpoint name (e.g., "inference_api") |
| batch_size | int | 32 | Batch size for reranking |
| gen_options | dict | None | Additional generation options |

### Setup Requirements
```bash
export MODAL_TOKEN=<your-modal-token>
export MODAL_TOKEN_SECRET=<your-modal-secret>
```

### Methods
#### get_scores

```python
def get_scores(self, query: str, documents: List[str]) -> List[float]
```

**Returns:** List of float scores.

**Example:**
```python
reranker = ModalReranker(
    app_name="ai2-scholar-qa",
    api_name="inference_api",
    batch_size=256
)
scores = reranker.get_scores("climate change", passages)
```
```