Metadata-Version: 2.4
Name: open-science-assistant
Version: 0.7.0
Summary: Open Science Assistant - An extensible AI assistant platform for open science projects
Project-URL: Homepage, https://github.com/OpenScience-Collective/osa
Project-URL: Documentation, https://github.com/OpenScience-Collective/osa#readme
Project-URL: Repository, https://github.com/OpenScience-Collective/osa
Project-URL: Issues, https://github.com/OpenScience-Collective/osa/issues
Author: Open Science Collective
Maintainer-email: Yahya Shirazi <yahya@osc.earth>
License: MIT
License-File: LICENSE
Keywords: ai,assistant,bids,eeglab,hed,langchain,langgraph,open-science
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: platformdirs>=4.5.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.20.0
Provides-Extra: dev
Requires-Dist: apscheduler<4.0.0,>=3.10.0; extra == 'dev'
Requires-Dist: beautifulsoup4>=4.14.0; extra == 'dev'
Requires-Dist: fastapi>=0.125.0; extra == 'dev'
Requires-Dist: langchain-anthropic>=1.3.0; extra == 'dev'
Requires-Dist: langchain-community>=0.4.0; extra == 'dev'
Requires-Dist: langchain-core>=1.2.0; extra == 'dev'
Requires-Dist: langchain-litellm>=0.2.0; extra == 'dev'
Requires-Dist: langchain-openai>=1.1.0; extra == 'dev'
Requires-Dist: langchain>=1.2.0; extra == 'dev'
Requires-Dist: langgraph-checkpoint-postgres>=3.0.0; extra == 'dev'
Requires-Dist: langgraph>=1.0.0; extra == 'dev'
Requires-Dist: litellm>=1.50.0; extra == 'dev'
Requires-Dist: lxml>=6.0.0; extra == 'dev'
Requires-Dist: markdownify>=1.1.0; extra == 'dev'
Requires-Dist: mypy>=1.19.0; extra == 'dev'
Requires-Dist: pre-commit>=4.5.0; extra == 'dev'
Requires-Dist: psycopg[binary]>=3.3.0; extra == 'dev'
Requires-Dist: pyalex>=0.19; extra == 'dev'
Requires-Dist: pydantic-settings>=2.12.0; extra == 'dev'
Requires-Dist: pygithub>=2.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.2.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Requires-Dist: uv>=0.5.0; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.38.0; extra == 'dev'
Provides-Extra: observability
Requires-Dist: langfuse>=3.11.0; extra == 'observability'
Provides-Extra: server
Requires-Dist: apscheduler<4.0.0,>=3.10.0; extra == 'server'
Requires-Dist: beautifulsoup4>=4.14.0; extra == 'server'
Requires-Dist: fastapi>=0.125.0; extra == 'server'
Requires-Dist: langchain-anthropic>=1.3.0; extra == 'server'
Requires-Dist: langchain-community>=0.4.0; extra == 'server'
Requires-Dist: langchain-core>=1.2.0; extra == 'server'
Requires-Dist: langchain-litellm>=0.2.0; extra == 'server'
Requires-Dist: langchain-openai>=1.1.0; extra == 'server'
Requires-Dist: langchain>=1.2.0; extra == 'server'
Requires-Dist: langgraph-checkpoint-postgres>=3.0.0; extra == 'server'
Requires-Dist: langgraph>=1.0.0; extra == 'server'
Requires-Dist: litellm>=1.50.0; extra == 'server'
Requires-Dist: lxml>=6.0.0; extra == 'server'
Requires-Dist: markdownify>=1.1.0; extra == 'server'
Requires-Dist: psycopg[binary]>=3.3.0; extra == 'server'
Requires-Dist: pyalex>=0.19; extra == 'server'
Requires-Dist: pydantic-settings>=2.12.0; extra == 'server'
Requires-Dist: pygithub>=2.8.0; extra == 'server'
Requires-Dist: python-dotenv>=1.2.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.38.0; extra == 'server'
Description-Content-Type: text/markdown

# 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
- **EEGLAB Assistant**: EEG analysis toolbox
- **NEMAR Assistant**: BIDS-formatted EEG, MEG, and iEEG dataset discovery

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

```bash
# From PyPI
pip install open-science-assistant

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

### Development Setup

```bash
# 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

```bash
# Set up your API key (get one at https://openrouter.ai/keys)
osa init

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

# Start an interactive chat session
osa chat -a hed

# Show all commands
osa --help
```

### API Server

Requires server dependencies: `pip install 'open-science-assistant[server]'`

```bash
# Start the API server
osa serve

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

### Configuration

```bash
# Show current config
osa config show

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

# Override API URL per-command
osa ask -a hed "What is HED?" --api-url https://api.osc.earth/osa-dev
```

### Deployment

OSA can be deployed via Docker:

```bash
# 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](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.

```bash
# 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`:

```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:

```bash
export OPENROUTER_API_KEY_MY_TOOL="your-openrouter-key"
```

3. Validate your configuration:

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

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

For the full guide, see the [community registry documentation](https://docs.osc.earth/osa/registry/).

## Documentation

Full documentation is available at **[docs.osc.earth/osa](https://docs.osc.earth/osa/)**.

## Development

```bash
# Run tests with coverage
uv run pytest --cov

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

## License

MIT
