Merge pull request #6 from CognitiveVR/add-documentation

Add documentation

Author: monazhu

.github/workflows/ci.yml

@@ -24,6 +24,14 @@ jobs:
       - name: Lint with ruff
         run: uv run ruff check src/ tests/
 
+      - name: Checkout slicer fields
+        uses: actions/checkout@v4
+        with:
+          repository: CognitiveVR/cvr-slicer
+          path: ../cvr-slicer
+          sparse-checkout: doc/slicer_fields.yaml
+        continue-on-error: true
+
       - name: Validate schema freshness
         run: |
           if [ -f "../cvr-slicer/doc/slicer_fields.yaml" ] || [ -f "../cvr-cortex/doc/slicer_fields.yaml" ]; then

CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md — cognitive3dpy contributor guide
+
+## Dev environment
+
+The project uses `uv`. To set up:
+
+```bash
+uv sync --all-extras
+```
+
+This installs the package, all dev dependencies, and the optional pandas extra.
+
+## Running tests
+
+```bash
+uv run pytest tests/ -q                          # all tests
+uv run pytest tests/test_transform.py -q         # single file
+```
+
+Tests use `respx` to mock HTTP calls — no real API credentials needed.
+
+## Architecture
+
+All data flows through a shared pipeline in `_transform.py`:
+
+```
+API JSON → pl.DataFrame → normalize_columns() → coerce_types() → [join_scene_names()] → [select_compact()] → to_output()
+```
+
+- `_transform.py` — all DataFrame transformation logic; the first place to look for type/schema issues
+- `_client.py` — HTTP client, auth headers, error handling
+- `_pagination.py` — session list pagination
+- `_lookups.py` — metadata resolution (scenes, objects, objectives); results are cached by project_id
+- `_filters.py` — builds the session filter payload sent to the API
+- Each public function lives in its own module (`sessions.py`, `events.py`, etc.)
+
+## Key conventions
+
+- **Polars internally, pandas only at the boundary** — all processing uses `polars.DataFrame`; `to_output()` is the only place pandas conversion happens
+- **Column naming** — `normalize_columns()` converts everything to `snake_case`; `c3d.*` API properties become `c3d_*` (e.g. `c3d.metrics.fps_score` → `c3d_metrics_fps_score`)
+- **Numeric metric columns are always Float64** — `coerce_types()` casts all `c3d_metrics_*`, `c3d_metric_components_*`, and `c3d_roomsize_meters` columns to `pl.Float64`, even when the API returns whole numbers as integers
+- **Empty DataFrames have explicit schemas** — functions return typed empty frames (not schema-less) when no data is found
+- **Date inputs** — all public functions accept `date`/`datetime` objects, epoch timestamps (int/float seconds), or `"YYYY-MM-DD"` strings
+
+## Release process
+
+Releases are fully automated via `python-semantic-release` on push to `main`. Use conventional commits:
+
+- `fix:` → patch bump
+- `feat:` → minor bump
+- `feat!:` or `BREAKING CHANGE:` footer → major bump
+- `chore:` / `docs:` → no release
+
+The CI workflow (`release.yml`) determines the next version, creates a git tag, builds with `uv`, and publishes to PyPI automatically. Do not manually edit the version in `pyproject.toml`.

README.html

@@ -186,3 +186,14 @@ All data-fetching functions support these session filters:
 - `project_id` — override the default set by `c3d_project()`
 - `output` — `"polars"` (default) or `"pandas"`
 - `warn_empty` — emit a `UserWarning` when 0 rows are returned (default `True`); set to `False` to suppress
+
+## Contributing
+
+```bash
+git clone https://github.com/CognitiveVR/cognitive3dpy.git
+cd cognitive3dpy
+uv sync --all-extras  # installs package + dev + pandas dependencies
+uv run pytest tests/  # run tests
+```
+
+Releases are automated via [python-semantic-release](https://python-semantic-release.readthedocs.io/) on push to `main`. Use [conventional commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:`) to trigger a release.