Getting Started¶

This guide will help you set up and start using the Open Science Assistant.

For Users (CLI)¶

Prerequisites¶

• Python 3.11+
• uv or pip

Install¶

pip install open-science-assistant
# or
uv pip install open-science-assistant

This installs a lightweight CLI (~7 dependencies) that connects to the OSA API.

Setup¶

Run the interactive setup to configure your API key:

osa init

You'll need your own API key. Either provider works:

• Anthropic (recommended): platform.claude.com/settings/keys. Keys start with sk-ant-.
• OpenRouter: openrouter.ai/keys. Keys start with sk-or-.

The setup will:

1. Prompt for your API key
2. Work out which provider it belongs to from the key's own prefix, so there is nothing to declare
3. Save it securely to your config directory (see paths below)
4. Test the connection to the API

Config directory by platform:

Alternatively, pass the key directly:

osa init --api-key sk-ant-your-key

Usage¶

# Ask a single question
osa ask -a hed "How do I annotate a button press?"

# Interactive chat session
osa chat -a hed

# Check API health
osa health

# See all commands
osa --help

You can also pass an API key per-command without saving it:

osa ask -a hed "What is HED?" --api-key sk-ant-your-key

Or set it via environment variable. Each provider has its own variable, ANTHROPIC_API_KEY or OPENROUTER_API_KEY:

export ANTHROPIC_API_KEY=sk-ant-your-key
osa ask -a hed "What is HED?"

export ANTHROPIC_API_KEY=sk-ant-your-key
osa ask -a hed "What is HED?"

$env:ANTHROPIC_API_KEY = "sk-ant-your-key"
osa ask -a hed "What is HED?"

For Developers (Server)¶

Prerequisites¶

• Python 3.11+
• uv package manager
• Git

Clone and Install¶

git clone https://github.com/OpenScience-Collective/osa
cd osa

# Install all dependencies (including server + dev)
uv sync

# Install pre-commit hooks
uv run pre-commit install

Configuration¶

Copy the example environment file:

cp .env.example .env

cp .env.example .env

Copy-Item .env.example .env

Edit .env with your settings:

# LLM provider: Claude Platform on AWS
ANTHROPIC_API_KEY=your-key-here
ANTHROPIC_BASE_URL=https://aws-external-anthropic.us-east-2.api.aws
ANTHROPIC_WORKSPACE_ID=wrkspc_your-workspace-id

# One of claude-haiku-4-5 (default) or claude-sonnet-5-5; keep this a Claude model
DEFAULT_MODEL=claude-haiku-4-5

# Optional: LangFuse for observability
LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_SECRET_KEY=your-secret-key
LANGFUSE_HOST=https://cloud.langfuse.com

ANTHROPIC_BASE_URL and ANTHROPIC_WORKSPACE_ID go together: the AWS endpoint requires an anthropic-workspace-id header, so setting the base URL without the workspace id fails at request time. Leave both unset to talk to api.anthropic.com with a first-party key instead.

OPENROUTER_API_KEY is still read, but only as a bring-your-own-key path; it is never the platform default. See .env.example for every variable with its own notes.

Running the Server¶

# Start the FastAPI server
uv run uvicorn src.api.main:app --reload --port 38528

# Or use the CLI
uv run osa serve

The API will be available at http://localhost:38528.

Running Tests¶

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest --cov

# Run LLM integration tests (real paid calls; needs ANTHROPIC_API_KEY)
uv run pytest -m llm

API Endpoints¶

Next Steps¶

• Read the Architecture documentation
• Explore available tools
• Check the CLI Reference