openconceptlab 0.2.0: the API client as an importable core package

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q

CLAUDE.md

@@ -13,15 +13,15 @@ pip install -e ".[dev]"
 
 ## Architecture
 
-- **`src/ocl_cli/api_client.py`** — Sync HTTP client with all high-level API methods. Business logic lives here (not in Click commands) so it can be reused by a future MCP server wrapper.
+- **`src/openconceptlab/client.py`** — The API client is the open core package `openconceptlab` (`src/openconceptlab/client.py`). `ocl_cli.api_client` is a shim. Put API logic in the core; keep Click and output formatting in `ocl_cli`.
 - **`src/ocl_cli/config.py`** — Server registry and auth token resolution. Config stored at `~/.ocl/config.json`.
 - **`src/ocl_cli/output.py`** — JSON and human-readable table formatters.
 - **`src/ocl_cli/main.py`** — Click root group, global options, command registration.
 - **`src/ocl_cli/commands/`** — Thin Click command wrappers that parse args → call client → format output.
 
 ## Conventions
 
-- Click commands are thin wrappers. All API logic goes in `api_client.py`.
+- Click commands are thin wrappers. All API logic goes in the core client, `src/openconceptlab/client.py`.
 - Default `owner_type` is `"orgs"` for targeted operations, `"all"` for search/list.
 - Default `repo_type` is `"all"` for search/list, required for targeted operations.
 - `--json` / `-j` global flag outputs raw API JSON (unmodified) for agent consumption.

README.md

@@ -50,6 +50,23 @@ ocl --version
 ocl --help
 ```
 
+## Use as a Python library
+
+The `openconceptlab` package also installs the API client the `ocl` command uses:
+
+```python
+from openconceptlab import OCLAPIClient
+
+with OCLAPIClient(token="<your OCL API token>", client_name="my-tool/1.0") as ocl:
+    hits = ocl.search_concepts(query="malaria", owner="CIEL", repo="CIEL", limit=5)
+    for concept in hits["results"]:
+        print(concept["id"], concept["display_name"])
+```
+
+Pass `auth_scheme="Bearer"` to use an OIDC access token instead of an API token.
+
+HTTP errors raise `openconceptlab.APIError`, with `status_code`, `detail` and the parsed response `body`. Network failures raise the httpx exception (`httpx.TimeoutException` or `httpx.TransportError`) once retries run out. A client holds one token, so create one per user.
+
 ## Quick Start
 
 ### 1. Authenticate

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openconceptlab"
-version = "0.1.1"
-description = "Command-line interface for the Open Concept Lab API"
+version = "0.2.0"
+description = "Python client and command-line interface for the Open Concept Lab API"
 readme = "README.md"
 license = "MPL-2.0"
 requires-python = ">=3.10"

src/ocl_cli/__init__.py

@@ -1,3 +1,7 @@
 """OCL CLI - Command-line interface for the Open Concept Lab API."""
 
-__version__ = "0.1.0"
+from openconceptlab import __version__
+
+CLIENT_NAME = f"ocl-cli/{__version__}"
+
+__all__ = ["CLIENT_NAME", "__version__"]