olira 1.0.0__tar.gz

olira-1.0.0/.devcontainer/Dockerfile

@@ -0,0 +1,14 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.245.0/containers/python-3
+ARG VARIANT=3.11-bookworm
+FROM mcr.microsoft.com/devcontainers/python:${VARIANT}
+
+# Install uv - fast Python package installer
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    mkdir -p /usr/local/bin && \
+    if [ -f /root/.cargo/bin/uv ]; then \
+        mv /root/.cargo/bin/uv /usr/local/bin/uv; \
+    elif [ -f /root/.local/bin/uv ]; then \
+        mv /root/.local/bin/uv /usr/local/bin/uv; \
+    fi && \
+    chmod +x /usr/local/bin/uv && \
+    uv --version

olira-1.0.0/.devcontainer/README.md

@@ -0,0 +1,19 @@
+# Development container
+
+VS Code dev container for the Olira Python SDK.
+
+## Setup
+
+1. Open this repository in VS Code.
+2. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.
+3. **Reopen in Container** (Command Palette → Dev Containers: Reopen in Container).
+4. After the container builds: `bash scripts/install-dev.sh` (PyPI only)
+
+API reference: [https://olira.ai/api-docs](https://olira.ai/api-docs) (Python SDK tab).
+
+## Commands
+
+- Pre-PR: `./scripts/pre-pr.sh`
+- Lint: `./scripts/lint.sh`
+- Tests: `./scripts/test.sh`
+- Version check: `./scripts/check-version.sh`

olira-1.0.0/.devcontainer/devcontainer.json

@@ -0,0 +1,74 @@
+{
+  "name": "Olira Python SDK",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "..",
+    "args": {
+      "VARIANT": "3.11-bookworm"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "/home/vscode/.venv/bin/python",
+        "python.linting.enabled": true,
+        "python.formatting.ruffPath": "/usr/local/py-utils/bin/ruff",
+        "python.linting.ruffPath": "/usr/local/py-utils/bin/ruff",
+        "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
+        "files.watcherExclude": {
+          "**/__pycache__/**": true,
+          "**/.mypy_cache/**": true,
+          "**/.pytest_cache/**": true,
+          "**/.ruff_cache/**": true,
+          "**/.venv/**": true,
+          "**/venv/**": true
+        },
+        "files.watcherInclude": [
+          "**/*.py",
+          "**/*.yaml",
+          "**/*.yml",
+          "**/*.json",
+          "**/*.toml"
+        ]
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "eamodio.gitlens",
+        "ms-python.mypy-type-checker"
+      ]
+    }
+  },
+  "remoteUser": "vscode",
+  "mounts": [
+    "source=${localEnv:HOME}/.ssh/,target=/home/vscode/.ssh/,type=bind,consistency=cached",
+    "source=olira-sdk-venv,target=/home/vscode/.venv,type=volume",
+    "source=olira-sdk-pycache,target=/tmp/pycache,type=volume",
+    "source=olira-sdk-mypy-cache,target=/tmp/.mypy_cache,type=volume",
+    "source=olira-sdk-pytest-cache,target=/tmp/.pytest_cache,type=volume",
+    "source=olira-sdk-ruff-cache,target=/tmp/.ruff_cache,type=volume",
+    "source=olira-sdk-uv-cache,target=/root/.cache/uv,type=volume"
+  ],
+  "containerEnv": {
+    "PYTHONPATH": "${workspaceFolder}/src",
+    "UV_PROJECT_ENVIRONMENT": "/home/vscode/.venv",
+    "PYTHONPYCACHEPREFIX": "/tmp/pycache",
+    "MYPY_CACHE_DIR": "/tmp/.mypy_cache",
+    "PYTEST_CACHE_DIR": "/tmp/.pytest_cache",
+    "RUFF_CACHE_DIR": "/tmp/.ruff_cache"
+  },
+  "features": {
+    "git": "latest"
+  },
+  "postCreateCommand": "bash -c 'sudo chown -R vscode:vscode /home/vscode/.venv /tmp/pycache /tmp/.mypy_cache /tmp/.pytest_cache /tmp/.ruff_cache 2>/dev/null || true; cd ${containerWorkspaceFolder} && bash scripts/install-dev.sh'",
+  "hostRequirements": {
+    "cpus": 2,
+    "memory": "4gb",
+    "storage": "8gb"
+  },
+  "runArgs": [
+    "--cpus=2",
+    "--memory=4g"
+  ]
+}

olira-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Pre-PR validation
+        env:
+          CI: "true"
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+          UV_INDEX_URL: https://pypi.org/simple/
+        run: ./scripts/pre-pr.sh

olira-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Read version
+        id: version
+        run: echo "version=$(grep -E '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')" >> "$GITHUB_OUTPUT"
+
+      - name: Reject pre-release versions
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          if [[ "$VERSION" =~ -(alpha|beta|rc) ]] || [[ "$VERSION" == *a* ]] || [[ "$VERSION" == *b[0-9] ]]; then
+            echo "::error::Refusing to publish pre-release version ($VERSION) to PyPI."
+            exit 1
+          fi
+          echo "Publishing stable version $VERSION to PyPI."
+
+      - name: Build package
+        env:
+          UV_INDEX_URL: https://pypi.org/simple/
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          print-hash: true

olira-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-20
+
+First public release of the Olira Python SDK (`pip install olira`).
+
+### Added
+
+- **Event logging** (`sdk:event-log`): `OliraClient.log()`, `log_batch()`, background queue with `flush()`, and module-level `olira.init()` / `olira.log()` / `olira.flush()`.
+- **Patient management** (`api:manage-patients`): create, read, update, delete, list, and batch-create patients; `ExternalIdentifier` for linking to EMR or partner IDs.
+- **Patient token** (`sdk:patient-token`): `get_patient_token()` for short-lived JWTs used with the [Olira MCP Patient State server](https://olira.ai/api-docs).
+- **Patient state read** (`sdk:state-read`): stable modules, event state modules, views, logs, events, and memories — REST-backed access to compiled patient state from Python.
+- **Historical data ingestion** (`sdk:historical-ingest`): JSONL file or inline record upload, two-phase confirm flow, job polling, and local pre-flight validation (`validate_ingestion_file`, `validate_ingestion_records`).
+- **Async client**: `AsyncOliraClient` with the same surface as `OliraClient`.
+- **Typed models**: `OliraLogType`, payload helpers (`EsasItem`, `LabResultItem`, …), and structured error types (`AuthError`, `ValidationError`, `RateLimitError`, `ServerError`).
+- **Examples**: runnable scripts under `examples/` for quickstart, patients, logging, ingestion, and state read.
+
+### Documentation
+
+- API reference: [https://olira.ai/api-docs](https://olira.ai/api-docs) (Python SDK tab)
+- Local reference: `SDK_DOCUMENTATION.md`

olira-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Olira AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

olira-1.0.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: olira
+Version: 1.0.0
+Summary: Olira Python SDK — event ingestion client for the Olira platform
+Project-URL: Documentation, https://olira.ai/api-docs
+Author-email: Olira AI <dev@olira.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: events,health,ingestion,olira,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Olira Python SDK
+
+Log ingestion, patient management, and patient token client for the Olira platform.
+
+## Install
+
+```bash
+pip install olira
+```
+
+## Documentation
+
+Full API reference: [https://olira.ai/api-docs](https://olira.ai/api-docs) (Python SDK tab).
+
+Local copy: [SDK_DOCUMENTATION.md](SDK_DOCUMENTATION.md).
+
+---
+
+## Authentication
+
+All SDK methods authenticate with an **Olira API key** (`olira_prod_...`). Create keys from the Olira Console under **Settings → API Keys**, selecting the scopes you need:
+
+| Scope                 | What it unlocks                       |
+| --------------------- | ------------------------------------- |
+| `sdk:event-log`       | Log events                            |
+| `api:manage-patients` | Create, read, update, delete patients |
+| `sdk:patient-token`   | Mint short-lived patient-scoped JWTs  |
+
+See [API key scopes](https://olira.ai/api-docs) for the full list.
+
+Pass the key to `OliraClient` or to `olira.init()`:
+
+```python
+import olira
+olira.init(api_key="olira_prod_...")  # or set OLIRA_API_KEY env var
+```
+
+---
+
+## Patient Management
+
+Patients must exist before you can log events against them. Use the `api:manage-patients` scope.
+
+Olira assigns a stable `id` to each patient at creation time. The `id` returned in the `Patient` object is what you use in all subsequent calls.
+
+```python
+from olira import OliraClient
+
+client = OliraClient(api_key="olira_prod_...")
+
+# Create — Olira assigns the id; store it for future calls
+patient = client.create_patient(
+    first_name="Jane",
+    last_name="Smith",
+    timezone="America/New_York",
+    primary_disease_site="breast",
+    disease_stage="II",
+)
+patient_id = patient.id
+
+# Get
+patient = client.get_patient(patient_id=patient_id)
+
+# List (paginated, returns PatientListResult)
+result = client.list_patients(limit=50, offset=0)
+for p in result.patients:
+    print(p.id, p.first_name, p.last_name)
+
+# Update (only supplied fields are changed)
+patient = client.update_patient(patient_id=patient_id, disease_stage="III")
+
+# Soft-delete
+client.delete_patient(patient_id=patient_id)
+```
+
+---
+
+## Event Logging
+
+Log a single event in the background (fire-and-forget):
+
+```python
+import olira
+from olira import OliraLogType
+
+olira.init(api_key="olira_prod_...")
+
+olira.log(
+    log_type=OliraLogType.USER_LOGIN,
+    patient_id=patient_id,  # id from patient.id
+)
+olira.flush()  # block until delivery
+```
+
+Send a batch directly and get back a result:
+
+```python
+from olira import OliraClient, LogSpec, OliraLogType, EsasItem
+
+client = OliraClient(api_key="olira_prod_...")
+result = client.log_batch([
+    LogSpec(log_type=OliraLogType.USER_LOGIN, patient_id=patient_id),
+    LogSpec(
+        log_type=OliraLogType.SYMPTOM_REPORT,
+        patient_id=patient_id,
+        payload={
+            "instrument": "esas_r",
+            "symptoms": [EsasItem(name="pain", score=4).model_dump()],
+        },
+    ),
+])
+print(f"accepted={result.accepted}, failed={result.failed}")
+client.close()
+```
+
+---
+
+## Patient Token
+
+Mint a short-lived JWT scoped to a single patient. Requires the `sdk:patient-token` scope.
+
+Use this when a patient device needs to communicate with the [Olira MCP Patient State server](https://olira.ai/api-docs) — pass the token as a Bearer header. The token expires after 15 minutes and is locked to the specified patient.
+
+```python
+from olira import OliraClient
+
+client = OliraClient(api_key="olira_prod_...")
+token = client.get_patient_token(patient_id=patient_id)
+
+print(token.access_token)  # forward this to the patient device
+print(token.expires_in)    # 900 (seconds)
+client.close()
+```
+
+---
+
+## Async client
+
+All methods are available on `AsyncOliraClient` as coroutines:
+
+```python
+import asyncio
+from olira import AsyncOliraClient, OliraLogType
+
+async def main():
+    async with AsyncOliraClient(api_key="olira_prod_...") as client:
+        patient = await client.create_patient(
+            first_name="Jane",
+            last_name="Smith",
+        )
+        await client.log(
+            log_type=OliraLogType.USER_LOGIN,
+            patient_id=patient.id,
+        )
+
+asyncio.run(main())
+```
+
+---
+
+## Error handling
+
+```python
+from olira import AuthError, ValidationError, RateLimitError, ServerError
+
+try:
+    client.log_batch([...])
+except AuthError:
+    # Invalid or revoked API key, or missing scope
+    ...
+except ValidationError:
+    # Bad request (400/404/422) — e.g. unknown event type or missing required field
+    ...
+except RateLimitError as e:
+    # Retry after e.retry_after seconds
+    ...
+except ServerError:
+    # Transient server error after all retries exhausted
+    ...
+```
+
+---
+
+## Contributing
+
+Dependencies are public PyPI packages only:
+
+```bash
+bash scripts/install-dev.sh
+./scripts/pre-pr.sh
+```

olira-1.0.0/README.md

@@ -0,0 +1,191 @@
+# Olira Python SDK
+
+Log ingestion, patient management, and patient token client for the Olira platform.
+
+## Install
+
+```bash
+pip install olira
+```
+
+## Documentation
+
+Full API reference: [https://olira.ai/api-docs](https://olira.ai/api-docs) (Python SDK tab).
+
+Local copy: [SDK_DOCUMENTATION.md](SDK_DOCUMENTATION.md).
+
+---
+
+## Authentication
+
+All SDK methods authenticate with an **Olira API key** (`olira_prod_...`). Create keys from the Olira Console under **Settings → API Keys**, selecting the scopes you need:
+
+| Scope                 | What it unlocks                       |
+| --------------------- | ------------------------------------- |
+| `sdk:event-log`       | Log events                            |
+| `api:manage-patients` | Create, read, update, delete patients |
+| `sdk:patient-token`   | Mint short-lived patient-scoped JWTs  |
+
+See [API key scopes](https://olira.ai/api-docs) for the full list.
+
+Pass the key to `OliraClient` or to `olira.init()`:
+
+```python
+import olira
+olira.init(api_key="olira_prod_...")  # or set OLIRA_API_KEY env var
+```
+
+---
+
+## Patient Management
+
+Patients must exist before you can log events against them. Use the `api:manage-patients` scope.
+
+Olira assigns a stable `id` to each patient at creation time. The `id` returned in the `Patient` object is what you use in all subsequent calls.
+
+```python
+from olira import OliraClient
+
+client = OliraClient(api_key="olira_prod_...")
+
+# Create — Olira assigns the id; store it for future calls
+patient = client.create_patient(
+    first_name="Jane",
+    last_name="Smith",
+    timezone="America/New_York",
+    primary_disease_site="breast",
+    disease_stage="II",
+)
+patient_id = patient.id
+
+# Get
+patient = client.get_patient(patient_id=patient_id)
+
+# List (paginated, returns PatientListResult)
+result = client.list_patients(limit=50, offset=0)
+for p in result.patients:
+    print(p.id, p.first_name, p.last_name)
+
+# Update (only supplied fields are changed)
+patient = client.update_patient(patient_id=patient_id, disease_stage="III")
+
+# Soft-delete
+client.delete_patient(patient_id=patient_id)
+```
+
+---
+
+## Event Logging
+
+Log a single event in the background (fire-and-forget):
+
+```python
+import olira
+from olira import OliraLogType
+
+olira.init(api_key="olira_prod_...")
+
+olira.log(
+    log_type=OliraLogType.USER_LOGIN,
+    patient_id=patient_id,  # id from patient.id
+)
+olira.flush()  # block until delivery
+```
+
+Send a batch directly and get back a result:
+
+```python
+from olira import OliraClient, LogSpec, OliraLogType, EsasItem
+
+client = OliraClient(api_key="olira_prod_...")
+result = client.log_batch([
+    LogSpec(log_type=OliraLogType.USER_LOGIN, patient_id=patient_id),
+    LogSpec(
+        log_type=OliraLogType.SYMPTOM_REPORT,
+        patient_id=patient_id,
+        payload={
+            "instrument": "esas_r",
+            "symptoms": [EsasItem(name="pain", score=4).model_dump()],
+        },
+    ),
+])
+print(f"accepted={result.accepted}, failed={result.failed}")
+client.close()
+```
+
+---
+
+## Patient Token
+
+Mint a short-lived JWT scoped to a single patient. Requires the `sdk:patient-token` scope.
+
+Use this when a patient device needs to communicate with the [Olira MCP Patient State server](https://olira.ai/api-docs) — pass the token as a Bearer header. The token expires after 15 minutes and is locked to the specified patient.
+
+```python
+from olira import OliraClient
+
+client = OliraClient(api_key="olira_prod_...")
+token = client.get_patient_token(patient_id=patient_id)
+
+print(token.access_token)  # forward this to the patient device
+print(token.expires_in)    # 900 (seconds)
+client.close()
+```
+
+---
+
+## Async client
+
+All methods are available on `AsyncOliraClient` as coroutines:
+
+```python
+import asyncio
+from olira import AsyncOliraClient, OliraLogType
+
+async def main():
+    async with AsyncOliraClient(api_key="olira_prod_...") as client:
+        patient = await client.create_patient(
+            first_name="Jane",
+            last_name="Smith",
+        )
+        await client.log(
+            log_type=OliraLogType.USER_LOGIN,
+            patient_id=patient.id,
+        )
+
+asyncio.run(main())
+```
+
+---
+
+## Error handling
+
+```python
+from olira import AuthError, ValidationError, RateLimitError, ServerError
+
+try:
+    client.log_batch([...])
+except AuthError:
+    # Invalid or revoked API key, or missing scope
+    ...
+except ValidationError:
+    # Bad request (400/404/422) — e.g. unknown event type or missing required field
+    ...
+except RateLimitError as e:
+    # Retry after e.retry_after seconds
+    ...
+except ServerError:
+    # Transient server error after all retries exhausted
+    ...
+```
+
+---
+
+## Contributing
+
+Dependencies are public PyPI packages only:
+
+```bash
+bash scripts/install-dev.sh
+./scripts/pre-pr.sh
+```