# Concentriq LS Python Client

Python client library for Proscia Concentriq Life Sciences API.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![codecov](https://codecov.io/gh/Proscia/concentriq-ls-python-client/branch/main/graph/badge.svg)](https://codecov.io/gh/Proscia/concentriq-ls-python-client)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Features

- **Complete API Coverage** - V1, V2, and V3 APIs
- **Multiple Auth Methods** - API Key, Basic, JWT, Session
- **Type Safe** - Full type hints with mypy support
- **Test Driven** - Comprehensive test coverage
- **Modern Python** - Python 3.10+ with Pydantic v2

## Quick Start

```python
from concentriq import ConcentriqClient
from concentriq.auth import ApiKeyAuth

# Create authenticated client
with ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=ApiKeyAuth(api_key="your-api-key")
) as client:
    # V1 API - Core resources
    image_sets = client.v1.image_sets.list()
    images = client.v1.images.list(filters={"imageSetId": 123})

    # V2 API - User management
    groups = client.v2.user_groups.list()

    # V3 API - Modern features
    studies = client.v3.studies.list()
    seed = client.v3.image_sets.generate_seed(image_set_id=123)
```

## Documentation

- **[Installation Guide](docs/installation.md)** - Setup, authentication, and configuration
- **[Usage Guide](docs/usage.md)** - Examples for V1, V2, and V3 APIs
- **[API Reference](docs/api-reference.md)** - Complete method documentation

## Installation

```bash
pip install concentriq-ls-client
```

Or with uv:

```bash
uv add concentriq-ls-client
```

## API Coverage

### V1 API (`/api/*`) - Core Resources
**Image Management:**
- ImageSets - CRUD + pagination + filters
- Images - List, get, download
- Folders - Full CRUD
- Annotations - Full CRUD

**Data & Metadata:**
- Metadata - Fields (with cached lookup by name) and values management
- DropdownResolver - Translate between dropdown option text and IDs
- Attachments - Upload and manage files

**Upload:**
- `upload_image()` - High-level helper: create image record + upload file (single-part or multipart)

**Organization:**
- Users - User management
- Organizations - Organization info
- Templates - Template CRUD
- Workflows - Workflow management
- Orders - Stain and recut orders

### V2 API (`/api/v2/*`) - Extended Features
- UserGroups - Group management with permissions
- Modules - External module configuration
- SavedDisplaySettings - Fluorescence display settings

### V3 API (`/api/v3/*`) - Modern Features
**Authentication & Security:**
- Auth - JWT tokens, API keys, whoami

**Research & Studies:**
- Studies - Full CRUD + fields/users/statistics
- ImageSets - Seed generation + blinding for research
- AuditLogs - Audit log status

**Configuration:**
- AnnotationClasses - Annotation type management
- ChannelGroups - Fluorescence channel groups
- AppConfig - Application configuration
- Users - User settings management
- Images - Image metadata

## Requirements

- Python 3.10+
- httpx >= 0.27.0
- pydantic >= 2.0.0

## Development

```bash
# Setup
uv sync --all-extras

# Run tests
uv run pytest tests/unit/ -v

# With coverage
uv run pytest tests/unit/ --cov=concentriq --cov-report=term-missing
```

See [CHANGELOG.md](CHANGELOG.md) for version history.

## License

Copyright 2025 Proscia Inc.

Licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Support

For issues and questions:

- [GitHub Issues](https://github.com/Proscia/concentriq-ls-python-client/issues)
