RC 0.3.0 candidate

.github/workflows/basic_tests.yml

@@ -31,8 +31,34 @@ jobs:
         run: tox
 
       - name: Upload coverage to Codecov
-        if: secrets.CODECOV_TOKEN != ''
         continue-on-error: true
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
+
+  wheel-smoke:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build wheel setuptools
+
+      - name: Build wheel
+        run: python -m build
+
+      - name: Smoke test installed wheel
+        run: |
+          python -m venv /tmp/circe-wheel-smoke
+          /tmp/circe-wheel-smoke/bin/pip install dist/*.whl
+          /tmp/circe-wheel-smoke/bin/circe --help
+          /tmp/circe-wheel-smoke/bin/python -c "import circe; print(circe.__version__)"

.github/workflows/ruff.yml

@@ -0,0 +1,29 @@
+name: Ruff
+
+on:
+  push:
+    branches: [ develop, main ]
+  pull_request:
+    branches: [ develop, main ]
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Ruff
+        run: pip install ruff
+
+      - name: Run Ruff linter
+        run: ruff check . --output-format=github
+
+      - name: Run Ruff formatter check
+        run: ruff format --check .
+

.gitignore

@@ -176,3 +176,6 @@ examples/*.json
 debug_app/.gemini_cache/
 debug_app/user_overrides.json
 debug_app/test_results.json
+
+.test_baseline.json
+.test_final.json

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

.readthedocs.yaml

@@ -18,9 +18,7 @@ formats:
 
 python:
   install:
-    - requirements: requirements.txt
     - method: pip
       path: .
       extra_requirements:
         - docs
-

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+## [0.3.0] - 2026-07-10
+
+### Added
+- Experimental Ibis execution engine for building and writing cohorts as relational expressions (`build_cohort()`, `write_cohort()`)
+- Support for snake_case YAML cohort definitions via `cohort_expression_from_yaml()`
+- Persistent caching of concept set resolution in the IBIS execution layer
+- `load_expression()` helper for loading cohort expressions from JSON, YAML, dict, or file paths
+
+### Fixed
+- ERA collapse ordering made deterministic across repeated executions
+- Collapse tie handling aligned with Java CIRCE-BE semantics
+- Era filter semantics restored with correct observation filtering
+- Nested correlated criteria now correctly applied within criteria groups
+- Package now importable without ibis installed
+- Pydantic deprecation warnings resolved
+
+### Changed
+- Dropped Python 3.8 support (minimum version is now 3.9)
+- Added PyYAML as a core dependency
+- Added `ibis`, `ibis-duckdb`, `ibis-postgres`, and `ibis-databricks` optional dependency groups
+
 ## [0.2.0] - 2026-02-25
 
 ### Added
@@ -17,58 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.0] - 2026-01-23
 
 ### Added
-
 - Initial Alpha Release of the CIRCE Python implementation.
 - Full parity with OHDSI CIRCE-BE Java library for cohort definition and SQL generation.
 - Expanded test suite with 3,400+ tests including parity checks.
-- Comprehensive documentation and GitHub Actions release workflows.
-
-## [Unreleased]
-
-### Planned
-- Performance optimizations for large cohort definitions
-- Additional output formats (JSON schema, XML)
-- Integration examples with common OMOP tools
----
-
-### Features
-
-- Support for Python 3.8, 3.9, 3.10, 3.11, and 3.12
-- Full OMOP CDM v5.x compatibility
-- Type hints throughout the codebase
-- Concept set expression handling with include/exclude logic
-- Window criteria for temporal relationships
-- Correlated criteria for complex cohort logic
-- Date adjustment strategies (DateOffsetStrategy)
-- Custom era strategies for drug exposures
-- Observation period and demographic criteria
-- Inclusion rules and censoring criteria
-- Result limits and ordinal expressions
-- Comprehensive error messages and validation warnings
-- Builder pattern for SQL generation
-- Pydantic models for data validation and serialization
-
-### Documentation
-
-- Complete README with installation instructions
-- Comprehensive CLI usage documentation
-- Python API examples and quick start guide
-- Contributing guidelines with development setup
-- Java class mapping reference for interoperability
-- Package structure documentation
-- Troubleshooting and FAQ sections
-
-### Technical Details
-
-- Built with Pydantic v2.0+ for robust validation
-- Uses typing-extensions for backward compatibility
-- Modular architecture matching Java CIRCE-BE structure
-- Extensive test coverage across all modules
-- Black, isort, flake8, and mypy for code quality
-- pytest with coverage reporting
-
-### Known Limitations
-
-- Negative control cohort classes yet implemented
-- Documentation website under development
-- Performance not yet optimized for extremely large cohorts (1000+ criteria)
+- Comprehensive documentation and GitHub Actions release workflows.

CLAUDE.md

@@ -0,0 +1,37 @@
+# Claude Instructions for circepy
+
+## Python Environment
+- Always use virtualenv for Python operations (don't rely on system Python or unauthenticated pip installs)
+- Activate the virtual environment before running Python commands or installing packages
+
+## Starting tasks - record testing state
+
+At the start of any task, record the state of tests as a baseline. It is not your job to fix pre-existing issues unless otherwise specified.
+
+Run tests with multiprocess for speed and store the state:
+```bash
+pytest -n auto --tb=short -v --json-report --json-report-file=.test_baseline.json
+```
+
+If the test state file is not created, check that pytest-xdist and pytest-json-report are installed in the virtualenv.
+
+## Pre-completion Checklist
+Before completing any task:
+
+1. Re-run pytest to verify no regressions:
+```bash
+pytest -n auto --tb=short -v --json-report --json-report-file=.test_final.json
+```
+
+Compare `.test_baseline.json` with `.test_final.json` — the final state should not show new failures.
+
+2. Run git pre-commit checks:
+```bash
+git pre-commit run --all-files
+```
+
+If pre-commit checks fail, fix the issues and re-run until they pass.
+
+## Git Workflow
+- Do not run `git commit` — the user will handle commits
+- Run pre-commit checks to validate code quality before marking tasks complete

CONTRIBUTING.md

@@ -10,7 +10,7 @@ This project follows the [OHDSI Code of Conduct](https://www.ohdsi.org/web/wiki/
 
 ### Prerequisites
 
-- Python 3.8 or higher
+- Python 3.9 or higher
 - Git
 - Basic understanding of the OMOP Common Data Model
 - Familiarity with the Java CIRCE-BE implementation (recommended)
@@ -19,21 +19,27 @@ This project follows the [OHDSI Code of Conduct](https://www.ohdsi.org/web/wiki/
 
 > [!NOTE]
 > This is a private development repository. Ensure you have access before attempting to clone.
+> The recommended contributor workflow uses `uv` and the checked-in `uv.lock` for a reproducible environment.
 
 1. Clone the repository
    ```bash
    git clone https://github.com/OHDSI/Circepy.git
    cd Circepy
    ```
 
-2. Install the package in development mode:
+2. Create the development environment:
    ```bash
-   pip install -e ".[dev]"
+   uv sync --extra dev
    ```
 
-3. Run tests to ensure everything is working:
+3. Install Git hooks:
    ```bash
-   pytest
+   uv run pre-commit install
+   ```
+
+4. Run tests to ensure everything is working:
+   ```bash
+   uv run pytest
    ```
 
 ## Development Guidelines
@@ -42,18 +48,15 @@ This project follows the [OHDSI Code of Conduct](https://www.ohdsi.org/web/wiki/
 
 We use the following tools to maintain code quality:
 
-- **Black** for code formatting
-- **isort** for import sorting
-- **flake8** for linting
-- **mypy** for type checking
+- **Ruff** for linting and formatting
+- **pre-commit** for running repository hooks before commit
 
 Run these tools before committing:
 
 ```bash
-black circe/
-isort circe/
-flake8 circe/
-mypy circe/
+uv run ruff check .
+uv run ruff format .
+uv run pre-commit run --all-files
 ```
 
 ### Type Hints
@@ -95,6 +98,10 @@ class TestCohortExpression:
         pass
 ```
 
+## Use of AI Tools
+
+Contributors may use AI tools to assist with development. If AI materially influenced a PR, please mention it in the PR description. Do not share secrets or sensitive data. Contributors remain responsible for correctness and license compliance.
+
 ## Pull Request Process
 
 1. Create a feature branch from `main`:
@@ -217,8 +224,8 @@ We follow [Semantic Versioning](https://semver.org/):
    - Update version in `pyproject.toml`
    - Update version in `circe/__init__.py`
    - Update `CHANGELOG.md` with release notes
-   - Ensure all tests pass: `pytest`
-   - Verify coverage is adequate: `pytest --cov`
+   - Ensure all tests pass: `uv run pytest`
+   - Verify coverage is adequate: `uv run pytest --cov`
 
 2. **Build the Package**
    ```bash
@@ -238,7 +245,7 @@ We follow [Semantic Versioning](https://semver.org/):
    twine upload --repository testpypi dist/*
 
    # Test installation
-   pip install --index-url https://test.pypi.org/simple/ ohdsi-circepy
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ ohdsi-circe-python-alpha
    ```
 
 4. **Create Git Tag**