arcobi-sdk 0.1.0b1__tar.gz

arcobi_sdk-0.1.0b1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+deploy/pool-server/credentials_pool.yaml

arcobi_sdk-0.1.0b1/LICENSE

@@ -0,0 +1,37 @@
+Arcobi SDK Licence
+
+Copyright (c) 2026 Arcobi. All rights reserved.
+
+This software and its accompanying documentation (the "Software") are the
+proprietary property of Arcobi. The Software is licensed, not sold.
+
+1. Grant. Subject to a current written agreement with Arcobi covering access to
+   the Arcobi data API, Arcobi grants you a non-exclusive, non-transferable,
+   revocable licence to install and use the Software, in unmodified form, solely
+   to access that API for your own internal business purposes.
+
+2. Restrictions. Except as that agreement or applicable mandatory law permits,
+   you may not: copy the Software other than as reasonably required for backup
+   or internal deployment; modify it or create derivative works from it;
+   distribute, sublicense, sell, rent, lease or otherwise make it available to
+   any third party; remove or alter any proprietary notice in it; or reverse
+   engineer, decompile or disassemble it.
+
+3. Reservation of rights. Arcobi retains all right, title and interest in and to
+   the Software. No rights are granted other than those expressly stated here.
+
+4. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+5. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
+   ARCOBI SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+   IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+   CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.
+
+6. Termination. This licence terminates automatically if you breach it, or when
+   your agreement with Arcobi ends. On termination you must stop using the
+   Software and delete all copies in your possession.
+
+7. Third-party components. The Software depends on separately distributed
+   third-party packages, which remain governed by their own licences.

arcobi_sdk-0.1.0b1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: arcobi-sdk
+Version: 0.1.0b1
+Summary: Fetch, align and export energy-market time-series data (Datahub), with an optional shared credential pool.
+Project-URL: Documentation, https://sdk.arcobi.com
+Author: Arcobi
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Keywords: aeso,data,datahub,energy,ercot,ieso,time-series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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.25
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12
+Provides-Extra: all
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'all'
+Requires-Dist: pyarrow>=14; extra == 'all'
+Requires-Dist: pydantic-settings>=2.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
+Provides-Extra: excel
+Requires-Dist: xlwings>=0.30; extra == 'excel'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14; extra == 'parquet'
+Provides-Extra: pool-server
+Requires-Dist: fastapi>=0.110; extra == 'pool-server'
+Requires-Dist: psycopg[binary,pool]>=3.1; extra == 'pool-server'
+Requires-Dist: pydantic-settings>=2.0; extra == 'pool-server'
+Requires-Dist: pyyaml>=6.0; extra == 'pool-server'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'pool-server'
+Description-Content-Type: text/markdown
+
+# arcobi-sdk
+
+Load energy-market time-series data from Datahub, align it on a time grid, and export it to a
+DataFrame, CSV, Parquet or JSON. Optionally share a pool of vendor credentials across many jobs
+through a small lease service. It takes you from the API to a clean, aligned frame or file,
+ready for the features and models you build on top.
+
+```bash
+pip install arcobi-sdk                 # extraction + export + pool client
+pip install "arcobi-sdk[parquet]"      # + Parquet export
+pip install "arcobi-sdk[pool-server]"  # + the credential-pool service
+```
+
+## Quick start
+
+```python
+from datetime import datetime, timedelta
+
+from arcobi_sdk import DatahubClient, fetch_streams, to_csv
+
+end = datetime.now()
+start = end - timedelta(days=7)
+
+with DatahubClient(username="...", password="...") as client:
+    df = fetch_streams(
+        client, streams=[1001, 1002], start=start, end=end, names=["demand", "price"]
+    )
+
+to_csv(df, "week.csv")
+```
+
+`fetch_streams` fetches the streams one after another. To fetch in parallel, share the same
+client across threads: it is thread-safe and holds the account's single token. Never open a
+second client with the same account, Datahub allows one session per account (see the
+[credentials guide](https://sdk.arcobi.com/credentials)).
+
+Credentials can also come from the environment (`DATAHUB_USERNAME` / `DATAHUB_PASSWORD`,
+or a pre-issued `DATAHUB_BEARER_TOKEN`), or from a local `.env` file loaded with
+`arcobi_sdk.load_env()`. The [credentials guide](https://sdk.arcobi.com/credentials) covers every
+option and the live smoke test.
+
+## Sharing credentials across jobs
+
+If several processes share a handful of vendor accounts, run the pool service once and let each
+job lease a token. Leases carry a generic **priority level**: `0` is served first, then `1`, then
+`2`; the default names are `high`, `normal`, `low` and deployments may rename them.
+
+```python
+from arcobi_sdk import DatahubClient, fetch_streams
+from arcobi_sdk.pool import PoolClient
+
+pool = PoolClient("http://localhost:8002", api_key="...")
+with pool.lease(holder_id="nightly-report", priority="high") as lease:
+    with DatahubClient(token_provider=lease.token_provider) as client:
+        df = fetch_streams(client, [1001], start, end)
+```
+
+The token is refreshed by the service before it expires and the client picks the new one up
+mid-extraction. Running the service is described in the
+[credential-pool guide](https://sdk.arcobi.com/examples/credential-pool).
+
+## Command line and Excel
+
+Every install also provides a small CLI, handy for scripts, schedulers and spreadsheet macros:
+
+```bash
+arcobi-sdk check                                   # authenticate, print token expiry, release
+arcobi-sdk fetch --streams 1001,1002 --names demand,price \
+    --start 2024-01-01 --end 2024-01-08 --out week.csv
+```
+
+Exit codes are stable (0 ok, 2 bad arguments or config, 3 vendor or auth error, 4 no data) and
+errors are one `error: ...` line on stderr, so a VBA `Shell` call can act on them. For Excel,
+`ArcobiSdk.bas` is a ready-made macro module that runs the CLI and imports the CSV onto a
+sheet. It ships inside the installed package:
+
+```bash
+python -c "import importlib.resources as r; print(r.files('arcobi_sdk.excel') / 'vba')"
+```
+
+`pip install "arcobi-sdk[excel]"` additionally provides xlwings-based functions (`datahub_fetch`,
+`datahub_fetch_to_sheet`, `datahub_check`) for spill formulas and `RunPython`. The
+[Excel guide](https://sdk.arcobi.com/excel) walks through both paths.
+
+## What is in the box
+
+| Module | Purpose |
+|---|---|
+| `arcobi_sdk.datahub` | `DatahubClient`, `fetch_streams`, extraction planning, time-grid alignment, gap interpolation |
+| `arcobi_sdk.timeutils` | local-to-UTC conversion, timestamp naming |
+| `arcobi_sdk.io` | `to_csv`, `to_parquet`, `to_json`, timestamped output folders |
+| `arcobi_sdk.pool` | credential-pool client, priorities, wire protocol; server behind an extra |
+| `arcobi_sdk.cli` | `arcobi-sdk fetch / check / version` command line |
+| `arcobi_sdk.excel` | Excel helpers: value conversion, xlwings UDFs (extra `excel`), VBA module |
+
+## Documentation
+
+**<https://sdk.arcobi.com>** -- the guides referred to above, plus the API reference generated
+from these docstrings:
+
+| Guide | |
+|---|---|
+| [Installation](https://sdk.arcobi.com/installation) | extras, supported versions |
+| [Quick start](https://sdk.arcobi.com/quickstart) | first extraction end to end |
+| [Credentials](https://sdk.arcobi.com/credentials) | every way to authenticate, and the live smoke test |
+| [Credential pool](https://sdk.arcobi.com/examples/credential-pool) | running and deploying the pool service |
+| [Excel](https://sdk.arcobi.com/excel) | the VBA module and the xlwings UDFs |
+
+The same material ships in the source distribution on PyPI, under `docs/` and
+`deploy/pool-server/`. A wheel install carries the package only.
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+Tests do not need a database or network access. Tests marked `postgres` run only when
+`POOL_TEST_DATABASE_URL` points at a reachable PostgreSQL. Tests marked `live` call the real
+Datahub API and run only with `DATAHUB_LIVE=1`, credentials, and `DATAHUB_TEST_STREAM_ID`
+set (`uv run pytest -m live`).

arcobi_sdk-0.1.0b1/README.md

@@ -0,0 +1,123 @@
+# arcobi-sdk
+
+Load energy-market time-series data from Datahub, align it on a time grid, and export it to a
+DataFrame, CSV, Parquet or JSON. Optionally share a pool of vendor credentials across many jobs
+through a small lease service. It takes you from the API to a clean, aligned frame or file,
+ready for the features and models you build on top.
+
+```bash
+pip install arcobi-sdk                 # extraction + export + pool client
+pip install "arcobi-sdk[parquet]"      # + Parquet export
+pip install "arcobi-sdk[pool-server]"  # + the credential-pool service
+```
+
+## Quick start
+
+```python
+from datetime import datetime, timedelta
+
+from arcobi_sdk import DatahubClient, fetch_streams, to_csv
+
+end = datetime.now()
+start = end - timedelta(days=7)
+
+with DatahubClient(username="...", password="...") as client:
+    df = fetch_streams(
+        client, streams=[1001, 1002], start=start, end=end, names=["demand", "price"]
+    )
+
+to_csv(df, "week.csv")
+```
+
+`fetch_streams` fetches the streams one after another. To fetch in parallel, share the same
+client across threads: it is thread-safe and holds the account's single token. Never open a
+second client with the same account, Datahub allows one session per account (see the
+[credentials guide](https://sdk.arcobi.com/credentials)).
+
+Credentials can also come from the environment (`DATAHUB_USERNAME` / `DATAHUB_PASSWORD`,
+or a pre-issued `DATAHUB_BEARER_TOKEN`), or from a local `.env` file loaded with
+`arcobi_sdk.load_env()`. The [credentials guide](https://sdk.arcobi.com/credentials) covers every
+option and the live smoke test.
+
+## Sharing credentials across jobs
+
+If several processes share a handful of vendor accounts, run the pool service once and let each
+job lease a token. Leases carry a generic **priority level**: `0` is served first, then `1`, then
+`2`; the default names are `high`, `normal`, `low` and deployments may rename them.
+
+```python
+from arcobi_sdk import DatahubClient, fetch_streams
+from arcobi_sdk.pool import PoolClient
+
+pool = PoolClient("http://localhost:8002", api_key="...")
+with pool.lease(holder_id="nightly-report", priority="high") as lease:
+    with DatahubClient(token_provider=lease.token_provider) as client:
+        df = fetch_streams(client, [1001], start, end)
+```
+
+The token is refreshed by the service before it expires and the client picks the new one up
+mid-extraction. Running the service is described in the
+[credential-pool guide](https://sdk.arcobi.com/examples/credential-pool).
+
+## Command line and Excel
+
+Every install also provides a small CLI, handy for scripts, schedulers and spreadsheet macros:
+
+```bash
+arcobi-sdk check                                   # authenticate, print token expiry, release
+arcobi-sdk fetch --streams 1001,1002 --names demand,price \
+    --start 2024-01-01 --end 2024-01-08 --out week.csv
+```
+
+Exit codes are stable (0 ok, 2 bad arguments or config, 3 vendor or auth error, 4 no data) and
+errors are one `error: ...` line on stderr, so a VBA `Shell` call can act on them. For Excel,
+`ArcobiSdk.bas` is a ready-made macro module that runs the CLI and imports the CSV onto a
+sheet. It ships inside the installed package:
+
+```bash
+python -c "import importlib.resources as r; print(r.files('arcobi_sdk.excel') / 'vba')"
+```
+
+`pip install "arcobi-sdk[excel]"` additionally provides xlwings-based functions (`datahub_fetch`,
+`datahub_fetch_to_sheet`, `datahub_check`) for spill formulas and `RunPython`. The
+[Excel guide](https://sdk.arcobi.com/excel) walks through both paths.
+
+## What is in the box
+
+| Module | Purpose |
+|---|---|
+| `arcobi_sdk.datahub` | `DatahubClient`, `fetch_streams`, extraction planning, time-grid alignment, gap interpolation |
+| `arcobi_sdk.timeutils` | local-to-UTC conversion, timestamp naming |
+| `arcobi_sdk.io` | `to_csv`, `to_parquet`, `to_json`, timestamped output folders |
+| `arcobi_sdk.pool` | credential-pool client, priorities, wire protocol; server behind an extra |
+| `arcobi_sdk.cli` | `arcobi-sdk fetch / check / version` command line |
+| `arcobi_sdk.excel` | Excel helpers: value conversion, xlwings UDFs (extra `excel`), VBA module |
+
+## Documentation
+
+**<https://sdk.arcobi.com>** -- the guides referred to above, plus the API reference generated
+from these docstrings:
+
+| Guide | |
+|---|---|
+| [Installation](https://sdk.arcobi.com/installation) | extras, supported versions |
+| [Quick start](https://sdk.arcobi.com/quickstart) | first extraction end to end |
+| [Credentials](https://sdk.arcobi.com/credentials) | every way to authenticate, and the live smoke test |
+| [Credential pool](https://sdk.arcobi.com/examples/credential-pool) | running and deploying the pool service |
+| [Excel](https://sdk.arcobi.com/excel) | the VBA module and the xlwings UDFs |
+
+The same material ships in the source distribution on PyPI, under `docs/` and
+`deploy/pool-server/`. A wheel install carries the package only.
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+Tests do not need a database or network access. Tests marked `postgres` run only when
+`POOL_TEST_DATABASE_URL` points at a reachable PostgreSQL. Tests marked `live` call the real
+Datahub API and run only with `DATAHUB_LIVE=1`, credentials, and `DATAHUB_TEST_STREAM_ID`
+set (`uv run pytest -m live`).

arcobi_sdk-0.1.0b1/deploy/pool-server/Dockerfile

@@ -0,0 +1,30 @@
+# Credential-pool server: arcobi-sdk with the [pool-server] extra.
+# Build from the repository root:  docker build -f deploy/pool-server/Dockerfile -t arcobi-pool-server .
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    POOL_HOST=0.0.0.0 \
+    POOL_PORT=8002
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd --create-home --uid 10001 pool
+
+WORKDIR /build
+
+# Copy the sources first so the install sees the whole package.
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --upgrade pip && pip install "./[pool-server]" && rm -rf /build
+
+WORKDIR /app
+USER pool
+
+HEALTHCHECK --interval=15s --timeout=5s --retries=5 \
+    CMD curl -fsS "http://127.0.0.1:${POOL_PORT}/health" || exit 1
+
+EXPOSE 8002
+CMD ["python", "-m", "arcobi_sdk.pool.server"]

arcobi_sdk-0.1.0b1/deploy/pool-server/README.md

@@ -0,0 +1,108 @@
+# Credential-pool server
+
+A small FastAPI service that leases short-lived vendor tokens from a shared pool
+of accounts so several jobs can share a handful of credentials fairly. It ships
+in `arcobi-sdk` behind the `pool-server` extra; the client is in the default
+install.
+
+```bash
+pip install "arcobi-sdk[pool-server]"
+export POOL_DATABASE_URL=postgresql://pool:secret@localhost:5432/pool
+export POOL_API_KEY=$(openssl rand -hex 24)
+export POOL_CREDENTIALS_PATH=./credentials_pool.yaml
+python -m arcobi_sdk.pool.server
+```
+
+Or with Docker, from the repository root:
+
+```bash
+export POOL_API_KEY=$(openssl rand -hex 24) POOL_DB_PASSWORD=$(openssl rand -hex 16)
+cp deploy/pool-server/credentials_pool.example.yaml deploy/pool-server/credentials_pool.yaml
+docker compose -f deploy/pool-server/docker-compose.yml up --build
+```
+
+## Configuration
+
+All settings are environment variables prefixed `POOL_`.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `POOL_DATABASE_URL` | required | PostgreSQL DSN. Schema is created/migrated on start. |
+| `POOL_API_KEY` | required | Shared secret; clients send it as `X-API-Key`. |
+| `POOL_HOST` / `POOL_PORT` | `0.0.0.0` / `8002` | Listener. |
+| `POOL_PROVIDER` | `datahub` | Credential provider (`datahub`, `static`, or an entry point). |
+| `POOL_PROVIDER_OPTIONS` | `{}` | JSON keyword options for the provider, e.g. `{"timeout_seconds": 10}`. |
+| `POOL_CREDENTIALS_PATH` | unset | YAML file upserted on start (see `credentials_pool.example.yaml`). |
+| `POOL_REFRESH_BUFFER_SECONDS` | `90` | Refresh tokens this long before they expire. |
+| `POOL_REFRESH_RETRY_SECONDS` | `30` | Delay between failed refresh attempts. |
+| `POOL_HEARTBEAT_TIMEOUT_SECONDS` | `60` | Reclaim a lease whose last `ping` is older than this. |
+| `POOL_HANDOFF_GRACE_SECONDS` | `15` | Wait for `token_ack` this long before revoking the old token. |
+| `POOL_MAX_QUEUE_DEPTH` | `50` | Queued requests before `POST /leases` answers 503. |
+| `POOL_PRIORITY_LEVELS` | `high,normal,low` | Level names, most urgent first (level 0). |
+| `POOL_PRIORITY_DEFAULT` | `normal` | Level used when a request has no priority. |
+| `POOL_PRIORITY_ALIASES` | unset | Extra names, e.g. `urgent:0,batch:2`. |
+| `POOL_ALLOW_WS_QUERY_API_KEY` | `false` | Also accept `?api_key=` on the WebSocket URL (legacy clients). |
+| `POOL_METRICS` | `noop` | `noop` or `logging`; other sinks via `create_app(metrics=...)`. |
+| `POOL_LOG_LEVEL` | `INFO` | Python log level. |
+
+## Priorities
+
+A priority is an integer level; `0` is served first and requests within a level
+are first-in-first-out. Clients may send the integer or a level name
+(`"high"`), and a newcomer never overtakes queued requests of equal or higher
+urgency. Rename or add levels per deployment with the `POOL_PRIORITY_*`
+settings; the SDK ships no domain vocabulary.
+
+## Endpoints
+
+All REST endpoints except `/health` require the `X-API-Key` header.
+
+| Method | Path | Result |
+|---|---|---|
+| `POST` | `/leases` | `201` `status="granted"` with `token`, `expires_at`, `token_version`, `ws_url`; or `202` `status="queued"` with a real `lease_id`, `queue_position`, `estimated_wait_seconds`. `409` if the holder is already active or queued, `422` for an unknown priority, `503` if the queue is full or the vendor is down. |
+| `GET` | `/leases/{lease_id}` | Current state including the token once granted (lets a client that connects late pick it up). |
+| `DELETE` | `/leases/{lease_id}` | Release; `204` even when already finished, `404` if unknown. |
+| `GET` | `/status` | Pool size, active/available credentials, queue depth per level name. |
+| `GET` | `/health` | `status`, `db`, real `uptime_seconds`, `timestamp`. |
+
+WebSocket `/ws/{lease_id}` (API key in the handshake header):
+
+* server to client: `lease_granted`, `token_refreshed` (both carry `token`,
+  `token_type`, `expires_at`, `version`), `token_refresh_failed`,
+  `queue_position`, `lease_reclaimed`, `service_shutdown`, `pong`;
+* client to server: `ping` (persists the heartbeat, answered with `pong`),
+  `token_ack` (`version`), `checkin` (release and close).
+
+Lifecycle: a free credential is leased immediately; otherwise stale leases
+(no heartbeat for `POOL_HEARTBEAT_TIMEOUT_SECONDS`) are reclaimed and retried,
+and failing that the request is persisted as `queued`. A dispatcher grants
+queued requests in priority order whenever a lease is released or reclaimed and
+pushes `lease_granted`. Each active lease is refreshed before expiry; the old
+token is revoked after the client's `token_ack` or the grace period.
+
+## Client
+
+```python
+from arcobi_sdk.pool import PoolClient
+
+pool = PoolClient(
+    "http://localhost:8002", api_key="..."
+)  # or ARCOBI_POOL_URL / ARCOBI_POOL_API_KEY
+with pool.lease("job-42", priority="high", max_wait_seconds=300) as lease:
+    headers = lease.auth_header()  # always the latest token; refreshes arrive over the WebSocket
+    ...
+# leaving the block releases the lease (DELETE /leases/{id})
+```
+
+## Custom providers
+
+Implement `arcobi_sdk.pool.server.providers.base.CredentialProvider` and register
+it under the `arcobi_sdk.pool.providers` entry-point group; then set
+`POOL_PROVIDER` to its name. The `static` provider issues fake tokens and is
+meant for tests and local development only.
+
+## Tests
+
+The default suite runs on an in-memory store with the static provider. Store
+tests against PostgreSQL are marked `postgres` and run only when
+`POOL_TEST_DATABASE_URL` points at a reachable database.

arcobi_sdk-0.1.0b1/deploy/pool-server/credentials_pool.example.yaml

@@ -0,0 +1,23 @@
+# Credentials the pool server leases out.
+#
+# Copy to credentials_pool.yaml, fill in your vendor accounts and point
+# POOL_CREDENTIALS_PATH at it. The file is re-read on every start with upsert
+# semantics: existing accounts keep their id and lease history, changed
+# passwords are updated in place, and accounts removed from the file are
+# marked inactive (never deleted).
+#
+# Every key other than `username`, `provider` and `active` becomes part of the
+# credential's secret. The datahub provider needs `password`.
+
+credentials:
+  - username: "user_1"
+    password: "change-me"
+
+  - username: "user_2"
+    password: "change-me"
+
+  # Optional fields:
+  # - username: "user_3"
+  #   password: "change-me"
+  #   provider: datahub      # defaults to POOL_PROVIDER; other providers' entries are skipped
+  #   active: false            # keep the row but never lease it

arcobi_sdk-0.1.0b1/deploy/pool-server/docker-compose.yml

@@ -0,0 +1,53 @@
+# Local stack: PostgreSQL + the pool server.
+#
+#   export POOL_API_KEY=$(openssl rand -hex 24)
+#   export POOL_DB_PASSWORD=$(openssl rand -hex 16)
+#   cp credentials_pool.example.yaml credentials_pool.yaml   # then fill in real accounts
+#   docker compose -f deploy/pool-server/docker-compose.yml up --build
+#
+# No secret has a default: compose refuses to start until POOL_API_KEY and
+# POOL_DB_PASSWORD are set in the environment or an .env file next to this file.
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: pool
+      POSTGRES_PASSWORD: ${POOL_DB_PASSWORD:?required}
+      POSTGRES_DB: pool
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U pool -d pool"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    restart: unless-stopped
+
+  pool-server:
+    build:
+      context: ../..
+      dockerfile: deploy/pool-server/Dockerfile
+    ports:
+      - "${POOL_PORT:-8002}:8002"
+    environment:
+      POOL_DATABASE_URL: postgresql://pool:${POOL_DB_PASSWORD:?required}@postgres:5432/pool
+      POOL_API_KEY: ${POOL_API_KEY:?required}
+      POOL_PORT: "8002"
+      POOL_PROVIDER: ${POOL_PROVIDER:-datahub}
+      POOL_CREDENTIALS_PATH: /app/credentials_pool.yaml
+      POOL_REFRESH_BUFFER_SECONDS: ${POOL_REFRESH_BUFFER_SECONDS:-90}
+      POOL_HEARTBEAT_TIMEOUT_SECONDS: ${POOL_HEARTBEAT_TIMEOUT_SECONDS:-60}
+      POOL_HANDOFF_GRACE_SECONDS: ${POOL_HANDOFF_GRACE_SECONDS:-15}
+      POOL_MAX_QUEUE_DEPTH: ${POOL_MAX_QUEUE_DEPTH:-50}
+      POOL_LOG_LEVEL: ${POOL_LOG_LEVEL:-INFO}
+      POOL_METRICS: ${POOL_METRICS:-noop}
+    volumes:
+      - ./credentials_pool.yaml:/app/credentials_pool.yaml:ro
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: unless-stopped
+
+volumes:
+  pgdata:

arcobi_sdk-0.1.0b1/docs/CREDENTIALS.md

@@ -0,0 +1,98 @@
+# Configuring Datahub credentials
+
+The SDK never stores credentials itself. It looks for them in this order:
+
+1. **Constructor arguments** on `DatahubClient`:
+   `DatahubClient(username="...", password="...")` or `DatahubClient(bearer_token="...")`.
+2. **Environment variables**: `DATAHUB_USERNAME` + `DATAHUB_PASSWORD`, or `DATAHUB_BEARER_TOKEN`.
+3. **A leased token** from the credential pool: `DatahubClient(token_provider=lease.token_provider)`
+   (see the README section on sharing credentials).
+
+If none is found, constructing a client raises `ConfigurationError`.
+
+## Environment variables
+
+```bash
+# bash / zsh
+export DATAHUB_USERNAME="your-user"
+export DATAHUB_PASSWORD="your-password"
+```
+
+```powershell
+# PowerShell
+$env:DATAHUB_USERNAME = "your-user"
+$env:DATAHUB_PASSWORD = "your-password"
+```
+
+## A `.env` file for local work
+
+Create a `.env` file next to your script and keep it out of source control:
+
+```ini
+DATAHUB_USERNAME=
+DATAHUB_PASSWORD=
+# Alternatively a pre-issued token:
+# DATAHUB_BEARER_TOKEN=
+```
+
+Load it one of two ways:
+
+```python
+from arcobi_sdk import load_env, DatahubClient
+
+load_env()  # reads ./.env; never overrides variables already set
+client = DatahubClient()
+```
+
+```bash
+uv run --env-file .env python my_script.py
+```
+
+`load_env` is dependency-free and accepts `export KEY=VALUE`, quoted values and `#` comments.
+Pass `override=True` to let the file replace variables that are already set.
+
+## One session per account (concurrency)
+
+Datahub allows **one active session per account**. A second login with the same credentials
+is rejected with "Another user is currently using the API" (the SDK raises `DatahubAuthError`).
+Consequences:
+
+- To fetch several streams in parallel, share **one** `DatahubClient` across threads. The
+  client is thread-safe: token acquisition, refresh and release are serialised, so all threads
+  reuse the single token. Verified live: three streams fetched by three threads through one
+  client return exactly the same data as a sequential fetch.
+- Do not create one client per thread or per process with the same account. For many parallel
+  jobs use several accounts through the credential pool, where each job leases its own account.
+- Always release the token when done (`with DatahubClient() as client:` does this), otherwise
+  the account stays busy until the vendor-side session expires.
+
+## Pool client
+
+| Variable | Purpose |
+|---|---|
+| `ARCOBI_POOL_URL` | Base URL of the credential-pool service |
+| `ARCOBI_POOL_API_KEY` | API key sent in the `X-API-Key` header |
+
+Both can also be passed to `PoolClient(service_url, api_key=...)`.
+
+## Running the live test
+
+The default test suite never touches the network. A live smoke test exists and runs only when
+you opt in:
+
+```bash
+DATAHUB_LIVE=1 DATAHUB_TEST_STREAM_ID=<id> DATAHUB_TEST_STREAM_IDS=<id1>,<id2>,<id3> uv run pytest -m live
+```
+
+`DATAHUB_TEST_STREAM_ID` drives the single-stream smoke test; `DATAHUB_TEST_STREAM_IDS`
+(three ids) drives the concurrency test, which also asserts the one-session-per-account rule.
+
+With a `.env` file in the repo root the credentials are picked up automatically; the stream id
+can also go in that file. The test authenticates, fetches the last two days of the stream and
+writes a CSV to a temporary directory.
+
+## Good practice
+
+- Keep credentials out of source control; never commit a filled-in `.env`.
+- Prefer one account per job, or the credential pool, over sharing one login across processes.
+- Rotate a password that has been pasted into a chat, ticket or log.