Skip to content

Getting Started

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

Prerequisites

  • Python 3.12+
  • uv package manager
  • Git

Installation

Clone the Repository

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

Install Dependencies

# Install all dependencies
uv sync

# Install pre-commit hooks (for development)
uv run pre-commit install

Configuration

OSA uses environment variables for configuration. Copy the example file:

cp .env.example .env

Edit .env with your settings:

# LLM Provider (OpenRouter recommended)
OPENROUTER_API_KEY=your-key-here

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

# Optional: HED LSP for tag suggestions
HED_LSP_PATH=/path/to/hed-lsp

Running OSA

Development Server

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

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

CLI Usage

# Show available commands
uv run osa --help

# Interactive chat with HED assistant
uv run osa chat -a hed

# Single query to HED assistant
uv run osa ask -a hed "How do I validate a HED string?"

# Serve API (alternative to uvicorn)
uv run osa serve

API Endpoints

Endpoint Method Description
/health GET Health check
/info GET API information
/chat POST Chat with streaming response

Running Tests

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest --cov

# Run LLM integration tests (requires API key)
uv run pytest -m llm

Optional: HED Tag Suggestions

The HED assistant can suggest valid HED tags from natural language using the hed-lsp CLI tool.

Install hed-lsp

git clone https://github.com/hed-standard/hed-lsp.git
cd hed-lsp/server
npm install
npm run compile

Configure

Set the HED_LSP_PATH environment variable:

export HED_LSP_PATH=/path/to/hed-lsp

Or install globally:

cd hed-lsp/server
npm link  # Makes hed-suggest available globally

Usage

from src.tools.hed_validation import suggest_hed_tags

result = suggest_hed_tags.invoke({
    'search_terms': ['button press', 'visual flash'],
    'top_n': 5
})
# {'button press': ['Button', 'Response-button', ...],
#  'visual flash': ['Flash', 'Flickering', ...]}

Next Steps