Open Science Assistant (OSA)

An extensible AI assistant platform for open science projects, built with LangGraph/LangChain and FastAPI.

Overview

OSA provides domain-specific AI assistants for open science tools with:

• HED Assistant: Hierarchical Event Descriptors for neuroimaging annotation
• BIDS Assistant: Brain Imaging Data Structure (coming soon)
• EEGLAB Assistant: EEG analysis toolbox (coming soon)

Features:

• YAML-driven community registry - add a new assistant with just a config file
• Modular tool system for document retrieval, validation, and code execution
• Multi-source knowledge bases (GitHub, OpenALEX, Discourse forums, mailing lists)
• Embeddable chat widget for any website
• Production-ready observability via LangFuse

Installation

# From PyPI
pip install open-science-assistant

# Or with uv (recommended)
uv pip install open-science-assistant

Development Setup

# Clone and install in development mode
git clone https://github.com/OpenScience-Collective/osa.git
cd osa
uv sync --extra dev

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

Quick Start

CLI Usage

# Show available assistants
osa

# Ask the HED assistant a question
osa hed ask "What is HED?"

# Start an interactive chat session
osa hed chat

# Show all commands
osa --help
osa hed --help

API Server

# Start the API server
osa serve

# Or with uvicorn directly
uv run uvicorn src.api.main:app --reload --port 38528

Configuration

# Show current config
osa config show

# Set API keys for BYOK (Bring Your Own Key)
osa config set --openrouter-key YOUR_KEY

# Connect to remote server (uses BYOK)
osa hed ask "What is HED?" --url https://api.osc.earth/osa-dev

Deployment

OSA can be deployed via Docker:

# Pull and run
docker pull ghcr.io/openscience-collective/osa:latest
docker run -d --name osa -p 38528:38528 \
  -e OPENROUTER_API_KEY=your-key \
  ghcr.io/openscience-collective/osa:latest

# Check health
curl http://localhost:38528/health

See deploy/DEPLOYMENT_ARCHITECTURE.md for detailed deployment options including Apache reverse proxy and BYOK configuration.

Community Registry

OSA uses a YAML-driven registry to configure community assistants. Each community has a config.yaml that declares its documentation, system prompt, knowledge sources, and specialized tools.

# Directory structure
src/assistants/
    hed/config.yaml      # HED assistant configuration
    bids/config.yaml     # BIDS assistant (planned)

Adding a New Community

1. Create src/assistants/my-tool/config.yaml:

id: my-tool
name: My Tool
description: A research tool for neuroscience
status: available

# Required: Per-community OpenRouter API key for cost attribution
# Set the environment variable on your backend server
openrouter_api_key_env_var: "OPENROUTER_API_KEY_MY_TOOL"

system_prompt: |
  You are a technical assistant for {name}.
  {preloaded_docs_section}
  {available_docs_section}

documentation:
  - title: Getting Started
    url: https://my-tool.org/docs
    source_url: https://raw.githubusercontent.com/org/my-tool/main/docs/intro.md
    preload: true

github:
  repos:
    - org/my-tool

2. Set the API key environment variable on your backend:

export OPENROUTER_API_KEY_MY_TOOL="your-openrouter-key"

3. Validate your configuration:

uv run osa validate src/assistants/my-tool/config.yaml

4. Start the server - the /{community-id}/ask endpoint is auto-created.

Documentation:

• Community Onboarding Guide - Step-by-step onboarding process
• Configuration Reference - Complete reference for all config fields
• Troubleshooting Guide - Common issues and solutions

Documentation

For Community Onboarding

• Community Onboarding Guide - Complete walkthrough for adding your community to OSA (target: <15 minutes)
• Configuration Reference - Comprehensive reference for all config.yaml fields
• Troubleshooting Guide - Solutions for common configuration and deployment issues

For Deployment

• Deployment Architecture - Production deployment patterns and infrastructure options

Optional: HED Tag Suggestions

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

Installation

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

Configuration

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

Development

# Run tests with coverage
uv run pytest --cov

# Format code
uv run ruff check --fix . && uv run ruff format .

License

MIT