obi-one 0.1.dev1__tar.gz

obi_one-0.1.dev1/.coverage/.gitignore

@@ -0,0 +1 @@
+*

obi_one-0.1.dev1/.dockerignore

@@ -0,0 +1,8 @@
+**/*~
+**/*.log
+**/.DS_Store
+**/Thumbs.db
+**/__pycache__
+**/*.pyc
+**/*.swp
+**/*.egg-info

obi_one-0.1.dev1/.env.run-docker

@@ -0,0 +1,12 @@
+# for running the application with Docker
+
+export APP_DEBUG=true
+export LOG_LEVEL=DEBUG
+export LOG_SERIALIZE=false
+export LOG_BACKTRACE=true
+export LOG_DIAGNOSE=true
+export LOG_STANDARD_LOGGER__root=INFO
+export LOG_STANDARD_LOGGER__sqlalchemy.engine=INFO
+export LOG_STANDARD_LOGGER__sqlalchemy.pool=INFO
+
+export APP_DISABLE_AUTH=true

obi_one-0.1.dev1/.env.run-local

@@ -0,0 +1,52 @@
+# for running the application locally without Docker
+
+export APP_DEBUG=true
+export LOG_LEVEL=DEBUG
+export LOG_SERIALIZE=false
+export LOG_BACKTRACE=true
+export LOG_DIAGNOSE=true
+export LOG_STANDARD_LOGGER__root=INFO
+export LOG_STANDARD_LOGGER__sqlalchemy.engine=INFO
+export LOG_STANDARD_LOGGER__sqlalchemy.pool=INFO
+
+export UVICORN_HOST=127.0.0.1
+export UVICORN_PORT=8100
+
+export APP_DISABLE_AUTH=false
+export ACCOUNTING_DISABLED=true
+
+# Callbacks URL
+export API_URL=http://127.0.0.1:8100
+
+# Staging/Production Keycloak URL:
+export KEYCLOAK_URL=https://staging.cell-a.openbraininstitute.org/auth/realms/SBO
+# export KEYCLOAK_URL=https://cell-a.openbraininstitute.org/auth/realms/SBO
+
+# For use/testing with different EntityCore instances:
+# export ENTITYCORE_URL=http://127.0.0.1:8000
+export ENTITYCORE_URL=https://staging.cell-a.openbraininstitute.org/api/entitycore
+# export ENTITYCORE_URL=https://cell-a.openbraininstitute.org/api/entitycore
+
+# For use/testing with a local Launch System instance:
+# export LAUNCH_SYSTEM_URL=http://127.0.0.1:8001
+
+# For use/testing with launch-system in staging, start the AWS session as described in:
+# https://github.com/openbraininstitute/aws-terraform-deployment/blob/staging/bastion_host/BASTION_ACCESS.md
+# but use:
+# aws ssm start-session \
+#   --target "$INSTANCE_ID" \
+#   --document-name AWS-StartPortForwardingSessionToRemoteHost \
+#   --parameters '{"host":["staging.cell-a.openbraininstitute.org"],"portNumber":["443"],"localPortNumber":["4444"]}'
+# and verify the connection with:
+# curl -k https://127.0.0.1:4444/api/launch-system/version
+export LAUNCH_SYSTEM_URL=https://127.0.0.1:4444/api/launch-system
+export LAUNCH_SYSTEM_DISABLE_SSL_VERIFY=true
+
+# For use/testing with different Accounting instances:
+# export ACCOUNTING_BASE_URL=http://127.0.0.1:8002
+export ACCOUNTING_BASE_URL=https://staging.cell-a.openbraininstitute.org/api/accounting
+# export ACCOUNTING_BASE_URL=https://cell-a.openbraininstitute.org/api/accounting
+
+# Virtual Lab API:
+export VIRTUAL_LAB_API_URL=https://staging.cell-a.openbraininstitute.org/api/virtual-lab-manager
+# export VIRTUAL_LAB_API_URL=https://cell-a.openbraininstitute.org/api/virtual-lab-manager

obi_one-0.1.dev1/.env.test-docker

@@ -0,0 +1,7 @@
+# for testing the application with Docker
+
+export API_URL=http://127.0.0.1:8100
+export ENTITYCORE_URL=http://127.0.0.1:8000
+export LAUNCH_SYSTEM_URL=http://127.0.0.1:8001
+export ACCOUNTING_BASE_URL=http://127.0.0.1:8002
+export VIRTUAL_LAB_API_URL=http://127.0.0.1:8003

obi_one-0.1.dev1/.env.test-local

@@ -0,0 +1,7 @@
+# for testing the application locally without Docker
+
+export API_URL=http://127.0.0.1:8100
+export ENTITYCORE_URL=http://127.0.0.1:8000
+export LAUNCH_SYSTEM_URL=http://127.0.0.1:8001
+export ACCOUNTING_BASE_URL=http://127.0.0.1:8002
+export VIRTUAL_LAB_API_URL=http://127.0.0.1:8003

obi_one-0.1.dev1/.git-blame-ignore-revs

@@ -0,0 +1,3 @@
+# .git-blame-ignore-revs
+# Bulk addition of ty:ignore annotations to existing type errors
+997add810d58baafb1da28379ea0382e037ba810

obi_one-0.1.dev1/.gitattributes

@@ -0,0 +1,3 @@
+*.asc linguist-detectable=false
+*.hoc linguist-detectable=false
+*.mod linguist-detectable=false

obi_one-0.1.dev1/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,57 @@
+---
+name: Bug
+about: For identifying & tracking bugs
+title: ''
+labels: ''
+assignees: james-isbister
+
+---
+
+## Environment
+E.g. dev, staging, prod
+
+## Operating system & resolution
+E.g. Mac 14" (if possible, include also the resolution), Linux, etc
+
+## Browser & version
+E.g. chrome, safari (including version)
+
+## Description
+Clear and concise description
+
+## To Reproduce
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+## Expected behavior
+Clear and concise description 
+
+## Screenshots
+If applicable, add screenshots to help explain your problem
+
+## Additional context
+Add any other context about the problem here
+
+## Acceptance criteria
+- [ ] Include a checkbox list
+- [ ] Include a checkbox list
+- [ ] Include a checkbox list
+
+## Right panel fields
+
+### Assignee
+Will be added by default (the Product Owner)
+
+### Labels
+E.g. You can add 'planning' (for QA discussion), 'up next?' (for resource request), or other as applicable
+
+### Type
+Bug / Feature / Task
+
+### Projects
+Select 'OBI 2025-' project (plus others as relevant)
+Priority: P0 (higher), P1, or P2 (lower)
+Time estimate: In days

obi_one-0.1.dev1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,47 @@
+---
+name: Feature request
+about: For requests for new features
+title: ''
+labels: enhancement
+assignees: james-isbister
+
+---
+
+## Description
+Clear and concise description of what you would like to happen
+
+## Assets 
+E.g. Figma, design or other assets
+
+## Technical implementation & specs
+Including also dependencies or affected components
+
+## Describe alternatives considered
+Clear and concise description of any alternative solutions or features considered
+
+## Screenshots
+If applicable, add screenshots to help explain your problem
+
+## Additional context
+Add any other context about the problem here
+
+## Acceptance criteria
+- [ ] Include a checkbox list
+- [ ] Include a checkbox list
+- [ ] Include a checkbox list
+
+## Right panel fields
+
+### Assignee
+Will be added by default (the Product Owner)
+
+### Labels
+E.g. You can add 'planning' (for QA discussion), 'up next?' (for resource request), or other as applicable
+
+### Type
+Bug / Feature / Task
+
+### Projects
+Select 'OBI 2025-' project (plus others as relevant)
+Priority: P0 (higher), P1, or P2 (lower)
+Time estimate: In days

obi_one-0.1.dev1/.github/ISSUE_TEMPLATE/general.md

@@ -0,0 +1,32 @@
+---
+name: General
+about: For general OBI tickets (not bugs or feature requests)
+title: ''
+labels: ''
+assignees: james-isbister
+
+---
+
+## Description
+Clear & concise 
+
+## Acceptance criteria
+- [ ] Include a checkbox list
+- [ ] Include a checkbox list
+- [ ] Include a checkbox list
+
+## Right panel fields
+
+### Assignee
+Will be added by default (the Product Owner)
+
+### Labels
+E.g. You can add 'planning' (for QA discussion), 'up next?' (for resource request), or other as applicable
+
+### Type
+Bug / Feature / Task
+
+### Projects
+Select 'OBI 2025-' project (plus others as relevant)
+Priority: P0 (higher), P1, or P2 (lower)
+Time estimate: In days

obi_one-0.1.dev1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,45 @@
+name: PyPI
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - name: Check metadata
+        run: pipx run twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build
+          path: dist
+
+  upload_sdist:
+    name: Upload sdist
+    needs: [build_sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    if: github.event_name == 'release' && github.event.action == 'published'
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: build
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

obi_one-0.1.dev1/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Build and publish the Docker image
+
+permissions:
+  id-token: write # Required for OIDC authentication
+  contents: read # Standard permission for GitHub Actions
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish-to-aws-ecr:
+    runs-on: ubuntu-latest
+    env:
+      ENVIRONMENT: prod
+
+    steps:
+      - name: Clone repo
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+
+      - name: Authenticate with AWS CodeArtifact account
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: arn:aws:iam::985539765147:role/gh_codeartifact_read_all
+          aws-region: us-east-1
+
+      - name: Get CodeArtifact token
+        run: |
+          CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
+            --domain openbraininstitute \
+            --query authorizationToken \
+            --output text)
+          echo "::add-mask::$CODEARTIFACT_AUTH_TOKEN"
+          echo "UV_INDEX_OBI_CODEARTIFACT_PASSWORD=$CODEARTIFACT_AUTH_TOKEN" >> $GITHUB_ENV
+          echo "UV_INDEX_OBI_CODEARTIFACT_USERNAME=aws" >> $GITHUB_ENV
+          echo "CODEARTIFACT_TOKEN=$CODEARTIFACT_AUTH_TOKEN" >> $GITHUB_ENV
+
+      - name: Authenticate with AWS ECR account for pushing the image
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: arn:aws:iam::985539765147:role/gh_ecr_push_obi-one-private
+          aws-region: us-east-1
+
+      - name: Authenticate with AWS ECR
+        uses: aws-actions/amazon-ecr-login@v2
+        id: login-ecr
+
+      - name: Build, tag and push container
+        env:
+          IMAGE_NAME: ${{ steps.login-ecr.outputs.registry }}/obi-one
+        run: |-
+          make publish

obi_one-0.1.dev1/.github/workflows/run-tests.yml

@@ -0,0 +1,64 @@
+name: Run tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: arn:aws:iam::985539765147:role/gh_codeartifact_read_all
+          aws-region: us-east-1
+      - name: Get CodeArtifact token
+        run: |
+          CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
+            --domain openbraininstitute \
+            --query authorizationToken \
+            --output text)
+          echo "::add-mask::$CODEARTIFACT_AUTH_TOKEN"
+          echo "UV_INDEX_OBI_CODEARTIFACT_PASSWORD=$CODEARTIFACT_AUTH_TOKEN" >> $GITHUB_ENV
+          echo "UV_INDEX_OBI_CODEARTIFACT_USERNAME=aws" >> $GITHUB_ENV
+          echo "CODEARTIFACT_TOKEN=$CODEARTIFACT_AUTH_TOKEN" >> $GITHUB_ENV
+      - name: Check requirements
+        run: make check-deps
+      - name: Install mandatory and optional requirements
+        run: make install-all
+      - name: Run linters
+        run: make lint
+      - name: Run tests
+        run: make test-docker
+      - name: Run pip-audit
+        run: make pip-audit
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: openbraininstitute/obi-one
+          fail_ci_if_error: false
+          files: .coverage/coverage.xml
+          flags: pytest
+          verbose: true
+      - name: Cleanup
+        if: ${{ always() }}
+        run: |
+          make destroy

obi_one-0.1.dev1/.gitignore

@@ -0,0 +1,22 @@
+*.egg-info
+**/__pycache__/**
+**/build/*
+.DS_Store
+.idea
+**/analysis_output
+venv/
+.venv/
+temp/
+logs/
+*/arm64/
+**/arm64/
+examples/new_node_sets.json
+examples/node_sets.json
+dist/*
+.pypirc
+pip-audit-output.json
+*~
+examples/data/blueetl_data/output/
+/requirements.txt
+pip-audit-output.json
+coverage.xml

obi_one-0.1.dev1/CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OBI-ONE is a Python library and FastAPI service for biophysically-detailed brain modeling. It provides standardized workflows with cloud database integration (entitysdk), parameter scanning, and provenance tracking.
+
+## Common Commands
+
+```bash
+# Install dependencies (requires: brew install uv open-mpi boost cmake)
+make install
+
+# Run FastAPI service locally (http://127.0.0.1:8100/docs)
+make run-local
+
+# Run all tests with coverage
+make test-local
+
+# Run a single test file
+make test-file FILE=tests/path/to/test_file.py
+
+# Run schema tests only
+make test-schema
+
+# Lint (check only)
+make lint
+
+# Format and auto-fix
+make format
+make format FILE=obi_one/path/to/file.py
+
+# Update lock file (keeps entitysdk at latest)
+make compile-deps
+```
+
+## Architecture
+
+The codebase has two main source directories:
+
+- **`obi_one/`** - Core library package (installed as `obi-one`)
+- **`app/`** - FastAPI service wrapping the library
+
+### `obi_one/core/` - Framework Abstractions
+
+The core uses a **block-based compositional pattern**:
+
+- **`OBIBaseModel`** (`base.py`) - Pydantic base model with discriminator-based type field for polymorphic serialization. All domain models inherit from this.
+- **`Block`** (`block.py`) - Composable, parameterizable component. Any field set to a list becomes a dimension in a parameter scan.
+- **`ScanConfig`** (`scan_config.py`) - Abstract configuration composed of Blocks. Defines a modeling use case (e.g., `CircuitSimulationScanConfig`). Has class variables `name`, `description`, `single_coord_class_name`.
+- **`SingleConfigMixin`** (`single.py`) - Enforces that all parameters are single values (no lists). Used for execution-ready configs after scan expansion.
+- **`Task`** (`task.py`) - Abstract execution unit with an `execute()` method.
+- **`ScanGenerationTask`** (`scan_generation.py`) - Expands a ScanConfig into SingleConfigs via Cartesian product of multi-value parameters, then runs each.
+
+**Data flow:** `ScanConfig` (with list params) -> `ScanGenerationTask` -> multiple `SingleConfig` instances -> `Task.execute()` per config.
+
+### `obi_one/scientific/` - Domain Implementation
+
+- **`blocks/`** - Domain-specific blocks: stimuli, neuron sets, recordings, morphology locations, synaptic/neuronal manipulations
+- **`tasks/`** - Task implementations: circuit extraction, simulation, morphology operations, ephys extraction, ion channel modeling
+- **`unions/`** - Discriminated union types (`ScanConfigsUnion`, `TasksUnion`, etc.) and `config_task_map.py` for dispatch
+- **`from_id/`** - Lazy-loading wrappers that fetch data from entitysdk by ID
+- **`library/`** - Reusable scientific utility functions
+
+### `app/` - FastAPI Service
+
+- **`endpoints/`** - REST API routers (task launch, validation, metrics)
+- **`services/`** - Business logic (task submission with accounting/callbacks, morphology, validation)
+- **`dependencies/`** - FastAPI dependency injection (auth, db_client, accounting)
+- **`schemas/`** - Pydantic request/response models
+- **`config.py`** - Pydantic Settings with env-based configuration
+
+**Task submission flow:** Endpoint -> Task Service -> create EntitySDK Activity -> estimate accounting cost -> reserve credits -> submit to Launch System -> callback on completion.
+
+## Code Conventions
+
+- **Python 3.12** required (`>=3.12.2,<3.13`)
+- **Ruff** with `select = ["ALL"]` - very strict linting. Run `make format` before PRs.
+- **100 char line length**
+- **Google-style docstrings** (`pydocstyle convention = "google"`)
+- **Pydantic v2** for all data models
+- Tests are less strict on linting (annotations, docstrings, magic values, assert, private access, class-based test methods all allowed)
+- Use `Field(default=[...])` for mutable defaults on Pydantic model fields in tests to avoid RUF012
+- Coverage minimum: 30%, measured on both `app/` and `obi_one/`
+- Output files from examples should go in `obi-output/` outside the repo
+
+## Testing
+
+- **pytest** with `pytest-cov`, `pytest-freezer` (time), `pytest-httpx` (HTTP mocking)
+- Test paths: `tests/` and `examples/`
+- Tests mirror source structure: `tests/core/`, `tests/scientific/`, `tests/app/`, `tests/tasks/`
+- Tests use class-based organization (`class TestFoo:` with `def test_*` methods)
+- Env vars for testing loaded from `.env.test-local`
+- Always run `make format` before committing test files
+
+## Dependencies
+
+- Package manager: **uv** (>=0.9.22)
+- entitysdk is always kept at latest version (`make compile-deps` enforces this)
+- Key scientific deps: bluepysnap, brainbuilder, neurom, bluecellulab, bluepyefe, connectome-utilities, caveclient
+
+## CI/CD
+
+- PR checks: lint, test, pip-audit, codecov upload
+- Docs check: PRs must update `docs/` files (skip with `skip docs` label)
+- Docker: `make build` / `make publish`

obi_one-0.1.dev1/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+## Linting
+- Linting should be applied prior to making pull requests by running:
+`make format` or `make format FILE=obi_one/core/scan.py`. This will make minor automatic changes (removing empty lines etc.) and will list linting errors with suggestions of how they can be fixed. 
+- Linting should be used to improve code in the files being worked on or familiar to the developer. To avoid merge conflicts they should be sure that others are not working on the same files. 
+- In the future when all linting errors have been resolved, linting will be required by the CI before a PR can be approved.
+- Counts of linting errors by file can also be seen by running `make format_count` and counts of the types of errors with `make format_types`.
+
+## Output files
+- Example notebooks/scripts should ideally store output in a directory named **obi-output** that is at the same level as the obi-one repository i.e. outside the respistory.
+
+## Dependencies
+- Dependencies to a specific version/branch of another repository can be added to pyproject.toml under [tool.uv.sources]
+as `repo_name = { git = "https://github.com/repo_name/snap.git", branch = "branch_name" }`.  
+
+## Issues, Project Board, Milestones
+- All issues are tracked on the project board, where tickets can be created and moved appropriately: https://github.com/orgs/openbraininstitute/projects/42/views/1 
+- Issues may belong to individual product repositories (i.e. single_cell_lab) or the obi-one repository. This allows us to group the issues by product in the project board.
+- "Milestones" are also used for grouping to support sprint development. As issues belong to different repositories we created several generically named milestones (i.e. OBI-ONE Milestone A, OBI-ONE Milestone B, ...) in each product repository. This avoids having to create new milestones everytime a new milestone is begun. Instead we can assign a previously finished milestone (i.e. OBI-ONE Milestone C) to issues associated with the new milestone. 
+- The goal of each milestone can be viewed by clicking the "Project details" icon in the top right of the project board.
+
+
+# Logging: 
+The package's logging level can be set like this from your script / notebook:
+```
+L = logging.getLogger(obi.__name__)
+L.setLevel(logging.WARNING) 
+```
+
+or written to file:
+```
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    filename='app.log',  # optional: logs to a file instead of console
+    filemode='w'         # optional: overwrite the log file each time
+    force=True
+)
+```