furu 0.0.1__tar.gz

furu-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+          cd dashboard-frontend && bun install
+
+      - name: Install e2e dependencies
+        run: make dashboard-install-e2e
+
+      - name: Build frontend artifacts
+        run: make frontend-build
+
+      - name: Run tests
+        run: make test-all

furu-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,99 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - pyproject.toml
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Read version
+        id: version
+        run: |
+          python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path("pyproject.toml").read_text())
+          version = data["project"]["version"]
+          print(f"version={version}")
+          Path("version.txt").write_text(version)
+          PY
+          echo "version=$(cat version.txt)" >> $GITHUB_OUTPUT
+
+      - name: Check release
+        id: tag
+        run: |
+          git fetch --tags
+          if git rev-parse "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "should_release=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          if git diff -U0 HEAD^ HEAD -- pyproject.toml | grep -E '^[+-]version = "' >/dev/null; then
+            echo "should_release=true" >> $GITHUB_OUTPUT
+          else
+            echo "should_release=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Install dependencies
+        if: steps.tag.outputs.should_release == 'true'
+        run: |
+          uv sync --all-extras
+          cd dashboard-frontend && bun install
+
+      - name: Install e2e dependencies
+        if: steps.tag.outputs.should_release == 'true'
+        run: make dashboard-install-e2e
+
+      - name: Build frontend
+        if: steps.tag.outputs.should_release == 'true'
+        run: make frontend-build
+
+      - name: Run tests
+        if: steps.tag.outputs.should_release == 'true'
+        run: make test-all
+
+      - name: Build package
+        if: steps.tag.outputs.should_release == 'true'
+        run: uv build
+
+      - name: Create tag
+        if: steps.tag.outputs.should_release == 'true'
+        run: |
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Publish to PyPI
+        if: steps.tag.outputs.should_release == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        if: steps.tag.outputs.should_release == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "v${{ steps.version.outputs.version }}"
+          files: dist/*
+          generate_release_notes: true

furu-0.0.1/.gitignore

@@ -0,0 +1,231 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+**/.furu/data
+
+dashboard-frontend/node_modules/
+dashboard-frontend/src/routeTree.gen.ts
+dashboard-frontend/src/api/
+
+e2e/node_modules/
+e2e/test-results/
+e2e/playwright-report/
+
+*.tsbuildinfo
+orval.config.js
+vite.config.js
+
+/openapi.json
+data-furu/data

furu-0.0.1/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "cSpell.words": ["huldra"]
+}

furu-0.0.1/AGENTS.md

@@ -0,0 +1,265 @@
+# Repository Guidelines for AI Agents
+
+## Critical Rules
+
+**Always update `CHANGELOG.md`** for any user-visible change.
+
+**DO NOT USE** the following patterns in this codebase:
+- `typing.Optional` - Use `X | None` instead
+- `typing.Any` - Only acceptable when the type is truly unknowable at compile time (e.g., deserializing arbitrary JSON, interacting with untyped third-party libraries). Always prefer protocols, generics, or concrete types.
+- `object` as a type annotation - Use specific types, protocols, or generics instead
+- `dict` without specific value types - Use Pydantic models, dataclasses, or TypedDict instead of `dict[str, Any]` or `dict[str, object]`. Simple dicts like `dict[str, str]` or `dict[str, int]` should also be avoided if it is possible to know exactly what the keys and structure of the data is.
+- `try/except` for error recovery - Prefer happy path and let errors crash; only use try/except for cleanup or resource management
+- Backward compatibility shims or aliases - Do not add backward compatibility code; refactor all usages directly
+
+**ALWAYS** use `make` commands rather than running tools directly:
+- `make lint` not `uv run ruff check && uv run ty check`
+- `make test` not `uv run pytest`
+- `make check` for both lint and test
+
+**AFTER** making changes, verify your work:
+- For type/import changes: run `make lint`
+- For logic/behavior changes: run `make test` or `make test-all` or `make dashboard-test` or `make dashboard-test-e2e`
+
+- The project was renamed from huldra to furu. If I ever refer to huldra, assume I mean furu.
+
+---
+
+## Project Structure
+
+```
+src/furu/           # Main package (src layout - import as `furu`)
+  core/               # Furu and FuruList classes
+  storage/            # StateManager, MetadataManager
+  serialization/      # FuruSerializer (+ pydantic support)
+  runtime/            # Scoped logging, .env loading, tracebacks
+  adapters/           # Integrations (SubmititAdapter)
+  dashboard/          # FastAPI dashboard (optional)
+tests/                # pytest tests
+examples/             # Runnable examples
+dashboard-frontend/   # React/TypeScript dashboard frontend
+e2e/                  # Playwright end-to-end tests
+```
+
+---
+
+## Frontend Notes
+
+- Use shadcn/ui for frontend components.
+
+## Build, Test, and Lint Commands
+
+This project uses `uv` for dependency management.
+
+### Core Commands (use these)
+
+| Command | Description |
+|---------|-------------|
+| `make lint` | Run ruff check + ty type checker |
+| `make test` | Run pytest on `tests/` |
+| `make check` | Run lint + test |
+| `make build` | Build wheel/sdist (runs tests first) |
+| `make clean` | Remove caches and build artifacts |
+
+### Running a Single Test
+
+```bash
+# Run a specific test file
+uv run pytest tests/test_furu_core.py -v
+
+# Run a specific test function
+uv run pytest tests/test_furu_core.py::test_exists_reflects_success_state -v
+
+# Run tests matching a pattern
+uv run pytest -k "test_load" -v
+```
+
+### Dashboard Commands
+
+| Command | Description |
+|---------|-------------|
+| `make dashboard-dev` | Start dev servers (backend + frontend) |
+| `make dashboard-test` | Run dashboard backend tests |
+| `make dashboard-test-e2e` | Run Playwright e2e tests |
+| `make dashboard-test-all` | Run all dashboard tests |
+
+### Frontend Commands
+
+| Command | Description |
+|---------|-------------|
+| `make frontend-lint` | Run frontend TypeScript type checker |
+| `make frontend-test` | Run frontend unit tests |
+| `make frontend-build` | Build frontend for production |
+| `make frontend-generate` | Generate OpenAPI spec and TypeScript client |
+
+---
+
+## Code Style
+
+### Imports
+
+Order imports as: stdlib, third-party, local. Use absolute imports for cross-module references.
+
+```python
+import contextlib
+from pathlib import Path
+import chz
+from ..config import FURU_CONFIG
+```
+
+### Type Annotations
+
+- **Required** on all public APIs (functions, methods, class attributes)
+- Use modern syntax: `X | None` not `Optional[X]`
+- Use concrete types, not `Any`
+- Use generics where reasonable: `class Furu[T](ABC):`
+
+```python
+# Good - specific types
+def process(data: dict[str, str]) -> list[int] | None:
+    ...
+
+# Good - use Pydantic models or dataclasses for structured data
+class UserConfig(BaseModel):
+    name: str
+    settings: dict[str, str]
+
+def load_config(path: Path) -> UserConfig:
+    ...
+
+# Bad - DO NOT USE
+def process(data: Dict[str, Any]) -> Optional[List[int]]:
+    ...
+
+# Bad - DO NOT USE untyped dicts
+def load_config(path: Path) -> dict[str, Any]:  # NO - use a model
+    ...
+```
+
+### Naming Conventions
+
+- `snake_case` for functions, variables, module names
+- `PascalCase` for classes
+- `UPPER_SNAKE_CASE` for constants
+- Private/internal names prefixed with `_` (e.g., `_FuruState`, `_iso_now`)
+
+### Error Handling
+
+**Prefer happy path with early errors over defensive checks.** Don't wrap code in if-statements to handle error cases - let it crash or raise explicitly.
+
+```python
+# Good - assume happy path, crash if invariant violated
+data = json.loads(path.read_text())
+
+# Good - explicit early error instead of nested ifs
+if not condition:
+    raise ValueError("condition must be true")
+# proceed with happy path...
+
+# Bad - defensive if-checks for non-happy paths
+if path.exists():
+    data = json.loads(path.read_text())
+else:
+    data = {}  # NO - hides bugs, use happy path
+
+# Bad - swallowing errors
+try:
+    data = json.loads(path.read_text())
+except Exception:
+    data = {}  # NO - this hides bugs
+```
+
+**Only use try/except for:**
+1. Resource cleanup (use `contextlib.suppress` for ignoring cleanup errors)
+2. Converting exceptions to domain-specific errors
+3. Explicit user-facing error messages
+
+### Formatting
+
+- 4-space indentation
+- Line length: follow ruff defaults
+- Use trailing commas in multi-line structures
+- Prefer small, focused functions over large ones
+
+---
+
+## Testing Guidelines
+
+- All tests in `tests/` directory using pytest
+- Use `tmp_path` fixture for temporary directories
+- Use `furu_tmp_root` fixture (from `conftest.py`) for isolated Furu config
+- Keep tests deterministic - no writing to project root
+- Test functions named `test_<description>`
+
+```python
+def test_exists_reflects_success_state(furu_tmp_root) -> None:
+    obj = Dummy()
+    assert obj.exists() is False
+    obj.load_or_create()
+    assert obj.exists() is True
+```
+
+### Test Coverage Requirements
+
+**ALWAYS write extensive tests when adding new features.** Tests should cover:
+
+1. **Happy path** - The feature works as expected with valid inputs
+2. **Edge cases** - Empty inputs, boundary values, None/null values
+3. **Filter combinations** - When adding filters, test each filter individually AND in combination
+4. **Error cases** - Invalid inputs, missing data, malformed requests
+5. **Integration** - Test the full stack (API endpoints, not just internal functions)
+
+For dashboard features specifically:
+- Add tests in `tests/dashboard/test_scanner.py` for scanner/filtering logic
+- Add tests in `tests/dashboard/test_api.py` for API endpoint behavior
+- Update `dashboard-frontend/src/api.test.ts` for frontend schema validation
+
+Example test structure for a new filter:
+```python
+def test_filter_by_new_field(furu_tmp_root) -> None:
+    """Test filtering by the new field."""
+    # Setup: create experiments with different field values
+    # Test: filter returns only matching experiments
+    # Verify: correct count and correct experiments returned
+
+def test_filter_by_new_field_no_match(furu_tmp_root) -> None:
+    """Test filter returns empty when no experiments match."""
+
+def test_filter_by_new_field_combined(furu_tmp_root) -> None:
+    """Test new filter works in combination with existing filters."""
+```
+
+### Dashboard Test Performance
+
+**Use module-scoped fixtures for read-only tests.** Creating experiments is slow, so:
+
+1. **Prefer `populated_furu_root`** (module-scoped) over `temp_furu_root` (function-scoped)
+2. **Extend `_create_populated_experiments()`** in `conftest.py` when you need new test data
+3. **Only use `temp_furu_root`** when tests must mutate state or need isolated data
+
+```python
+# Good - uses shared fixture, fast
+def test_filter_by_backend(client: TestClient, populated_furu_root: Path) -> None:
+    response = client.get("/api/experiments?backend=local")
+    assert response.json()["total"] == 3  # Uses pre-created data
+
+# Slow - creates experiments per test (avoid unless necessary)
+def test_something(client: TestClient, temp_furu_root: Path) -> None:
+    create_experiment_from_furu(...)  # Slow!
+```
+
+---
+
+## Commit Guidelines
+
+- Short, imperative subjects (often lowercase)
+- Examples: `fix typing`, `add raw data path to furu config`
+- Keep commits scoped; separate refactors from behavior changes
+
+---
+
+## Environment & Configuration
+
+- Local config from `.env` (gitignored); don't commit secrets
+- Storage defaults to `./data-furu/`; override with `FURU_PATH`
+- Python version: >=3.12

furu-0.0.1/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## v0.0.1
+- Rename the project to furu and reset versioning to the v0.0.x alpha series.
+- Update API surface, storage metadata, and documentation to match furu naming.