precisionai-agrieval 0.1.0.dev0__tar.gz

precisionai_agrieval-0.1.0.dev0/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF on commit, regardless of editor/OS settings.
+* text=auto eol=lf
+
+# Treat binary files as binary (no line-ending conversion).
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.JPG binary
+*.JPEG binary
+*.svg binary
+*.pdf binary
+*.ipynb text eol=lf

precisionai_agrieval-0.1.0.dev0/.gitignore

@@ -0,0 +1,203 @@
+# Existing project-specific ignores
+.venv/
+exports/
+lightning_logs/
+.streamlit/users.json
+.streamlit/secrets.toml
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.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
+temp/
+
+# 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
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.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
+.idea/
+
+# VS Code
+.vscode/
+
+# PyTorch / Machine Learning
+*.pth
+*.pt
+*.ckpt
+*.pkl
+*.h5
+*.hdf5
+*.onnx
+*.pb
+*.tflite
+*.tfl
+*.pdf
+checkpoints/
+models/
+weights/
+wandb/
+mlruns/
+.neptune/
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+*~
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+
+# Data files (uncomment if you don't want to track datasets)
+# *.csv
+# *.json
+# *.parquet
+# *.h5
+# *.hdf5
+# data/
+dataset/
+output/
+
+# packaging artifacts
+*.egg-info/
+dist/
+build/
+
+dummy_input.json

precisionai_agrieval-0.1.0.dev0/.pre-commit-config.yaml

@@ -0,0 +1,46 @@
+repos:
+  # ── File hygiene ────────────────────────────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        # Keep committed test/image fixtures small enough for fast clones and CI.
+        args: ["--maxkb=1800"]
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: debug-statements
+      - id: fix-byte-order-marker
+
+  # ── Ruff: lint + format + import sorting ───────────────────────────────────
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  # ── Type checking (pyright / pylance engine) ────────────────────────────────
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: python -m pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  # ── Tests + coverage (≥ 90%) ────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest (coverage ≥ 90%)
+        entry: python -m pytest
+        language: system
+        args: ["tests/emb/", "tests/seg/", "-q", "--tb=short", "--no-header"]
+        pass_filenames: false
+        always_run: true

precisionai_agrieval-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - Initial public release
+
+- `precisionai.agrieval.emb` — embedding evaluation: KNN retrieval benchmarking (nDCG, MAP, MRR, purity), geometry diagnostics, and interactive visualizations.
+- `precisionai.agrieval.seg` — semantic segmentation evaluation: per-class IoU, Dice/F1, accuracy, mIoU, mAcc, FWIoU from colour-coded masks.
+- Unified FastAPI server exposing both subpackages, plus a standalone segmentation CLI (`precisionai-agrieval-seg`).
+- Top-level re-exports on both subpackages so the primary entry points can be imported directly, e.g. `from precisionai.agrieval.emb import run_image2image_eval` and `from precisionai.agrieval.seg import run_seg_eval`.
+
+[Unreleased]: https://github.com/Precision-AI-Inc/agrieval/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Precision-AI-Inc/agrieval/releases/tag/v0.1.0

precisionai_agrieval-0.1.0.dev0/CLAUDE.md

@@ -0,0 +1,218 @@
+# Precision AI — Python Project Standards
+
+Apply these standards when writing, reviewing, or refactoring code in any PAI Python project.
+
+---
+
+## Environment
+
+- Python 3.10+, managed with `python -m venv .venv` (never conda)
+- Install: `pip install -e ".[dev]"` → installs all deps including pre-commit
+- Register hooks once: `pre-commit install`
+
+---
+
+## Project layout
+
+```
+precisionai/<namespace>/<subpackage>/
+  api/
+    routes/      # FastAPI route handlers (thin — delegate to services)
+    config.py    # env-var config only
+    app.py       # FastAPI app factory
+  schemas/       # Pydantic v2 request/response models
+  services/      # Business logic (evaluate.py, reporting.py, …)
+  metrics/       # Pure computation modules
+    __init__.py  # re-exports only — no logic
+docs/            # Sphinx (HTML + LaTeX/PDF)
+tests/<subpackage>/     # mirrors precisionai.<namespace>.<subpackage>, e.g. tests/emb/, tests/seg/
+examples/<subpackage>/  # standalone runnable scripts, e.g. examples/emb/, examples/seg/
+```
+
+---
+
+## pyproject.toml — canonical config
+
+```toml
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E","W","F","I","UP","B","SIM","N","C90","D","PT","RUF","PL","ANN","PERF","S"]
+ignore = [
+    "E501",    # enforced by ruff-format
+    "B008",    # FastAPI default-arg pattern
+    "SIM108",  # ternary readability
+    "D100","D104",          # module/package docstrings optional
+    "D203","D213",          # pydocstyle conflicts — always ignore these two
+    "PLR0913","PLR2004",    # arg count + magic values common in metrics/tests
+    "ANN401",              # Any is allowed for genuinely dynamic types
+    "S311",                # pseudo-random generators are intentional in scientific code
+    "S104",                # binding to 0.0.0.0 is intentional for a configurable server host
+]
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]
+"tests/<subpackage>/**" = ["D","PLR","ANN","S"]  # e.g. tests/emb/**, tests/seg/**
+"docs/conf.py"   = ["E402","UP031","ANN","S"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"          # enforces NumPy docstring style
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.isort]
+known-first-party = ["precisionai"]   # adjust namespace per project
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true  # formats code blocks inside docstrings
+
+[tool.pytest.ini_options]
+addopts = "--cov=precisionai --cov-report=term-missing --cov-fail-under=90"
+
+[tool.coverage.report]
+fail_under = 90
+exclude_lines = ["pragma: no cover","if __name__ == .__main__.:",
+                 "raise ImportError","except ImportError"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "standard"
+reportMissingImports = false
+reportMissingModuleSource = false
+```
+
+---
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks: [check-added-large-files (--maxkb=1800), check-yaml, check-json,
+            check-toml, end-of-file-fixer, trailing-whitespace,
+            check-merge-conflict, detect-private-key, debug-statements,
+            fix-byte-order-marker]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks: [ruff (--fix), ruff-format]
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: python -m pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  - repo: local
+    hooks:
+      - id: pytest
+        entry: python -m pytest
+        language: system
+        args: [tests/emb/, tests/seg/, -q, --tb=short, --no-header]
+        always_run: true
+```
+
+---
+
+## Code style
+
+### Imports
+- All imports at the **top of the file** — never inside functions
+- Optional/unavailable deps: module-level `try/except ImportError` with a flag variable
+- No silent fallbacks unless mathematically equivalent (document why)
+- `__init__.py` re-exports only — no logic, no comments between import blocks
+- `__all__` must be **alphabetically sorted**
+
+```python
+# optional dep pattern
+try:
+    import plotly.graph_objects as go  # type: ignore[import]
+    _PLOTLY_AVAILABLE = True
+except ImportError:
+    _PLOTLY_AVAILABLE = False
+
+# inside function that needs it
+if not _PLOTLY_AVAILABLE:
+    raise ImportError("plotly is required: pip install plotly") from None
+```
+
+### Docstrings
+- **NumPy style** on all public functions, classes, and modules
+- Module docstrings: plain English, no prefixes (no P0/P1/P2, no "original", no labels)
+- One-line summary in **imperative mood** ("Compute …", "Return …", "Save …")
+- Blank line between summary and extended description (D205)
+
+### Type hints
+- Required on **all** function signatures (public and private) — enforced by ruff (`ANN`) and pyright
+- Use `X | Y` union syntax (Python 3.10+), not `Union[X, Y]` or `(X, Y)` in isinstance
+- Use `Any` from `typing` for genuinely dynamic types — don't use `object` when methods will be called on it
+- pyright config lives in `[tool.pyright]` in `pyproject.toml` — never pass type-checker flags inline
+
+### Comments
+- Only when the **why** is non-obvious
+- No section-divider comments that describe what the code already says
+- No cryptic labels, no TODO/FIXME without a ticket reference
+
+### Exception handling
+- Always `raise X from err` or `raise X from None` inside `except` blocks (B904)
+
+### General
+- `len()` returns `int` — never `int(len(...))`
+- Loop variables not used in the body → rename to `_`
+- `assert a and b` in tests → split into separate asserts
+- `@pytest.fixture` not `@pytest.fixture()`
+- `pytest.raises` always includes `match=` parameter
+- No `# type: ignore[attr-defined]` when `Any` already covers the attribute
+
+---
+
+## Docs (Sphinx)
+
+```
+docs/
+  conf.py          # version from git tag, logo, LaTeX/fancyhdr, enumitem fix
+  index.rst        # toctree: readme, modules
+  modules.rst      # autodoc for all public submodules
+  requirements.txt # sphinx, sphinx-rtd-theme, myst-parser, sphinx-autodoc-typehints
+  Makefile         # make html | make latexpdf | make clean
+  assets/logo.png
+```
+
+- `conf.py` copies root `README.md` → `docs/readme.md` at build time
+- Version read from `git describe --tags --exact-match`, falls back to `0.0.0`
+
+---
+
+## Testing
+
+- Mirror package structure: `tests/<subpackage>/test_<module>.py` (e.g. `tests/emb/`, `tests/seg/`)
+- Shared fixtures in each subpackage's `tests/<subpackage>/conftest.py`
+- 90% coverage hard minimum — enforced by pytest and pre-commit
+- No mocks for database/filesystem unless truly unavoidable
+- Integration tests marked `@pytest.mark.integration` and excluded from default runs
+
+---
+
+## What to avoid
+
+| Pattern | Instead |
+|---|---|
+| `int(len(x))` | `len(x)` |
+| `isinstance(x, (A, B))` | `isinstance(x, A \| B)` |
+| `assert a and b` (tests) | two separate asserts |
+| `@pytest.fixture()` | `@pytest.fixture` |
+| `pytest.raises(ValueError)` | `pytest.raises(ValueError, match="…")` |
+| `raise X` inside except | `raise X from None` or `raise X from err` |
+| Deferred imports inside functions | Module-level try/except with flag |
+| Cryptic prefixes (P0–P4, "original") | Plain descriptive names |
+| `# type: ignore[attr-defined]` on `Any` | Remove — redundant |
+| `# noqa` suppression | Fix the underlying issue |
+| Silent fallback for optional dep | Raise `ImportError` with install hint |

precisionai_agrieval-0.1.0.dev0/CODE_OF_CONDUCT.md

@@ -0,0 +1,67 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**michael@precision.ai**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

precisionai_agrieval-0.1.0.dev0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing
+
+Thank you for your interest in contributing to Precision AI AgriEval.
+
+By participating in this project, you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Setup
+
+Requires Python 3.10+.
+
+```bash
+git clone https://github.com/Precision-AI-Inc/agrieval.git
+cd agrieval
+
+python -m venv .venv
+source .venv/bin/activate       # Windows: .venv\Scripts\activate
+
+pip install -e ".[dev]"
+pre-commit install
+```
+
+`pip install -e ".[dev]"` installs all dependencies including test, analysis, and pre-commit tooling. `pre-commit install` registers the hooks so they run automatically on every commit.
+
+## Making changes
+
+1. Create a branch from `main`.
+2. Make your changes.
+3. Add or update tests — coverage must remain at or above 90%.
+4. Commit. Pre-commit hooks run automatically and will block the commit if any check fails.
+
+If a hook auto-fixes files (ruff lint/format), stage the changes and commit again.
+
+## Pre-commit hooks
+
+| Hook | What it checks |
+|---|---|
+| File hygiene | Large files (>1800 KB), trailing whitespace, merge conflicts, private keys, debug statements, BOM removal |
+| `ruff` | Linting and import sorting (auto-fix); includes `ANN` rules that enforce PEP 484 annotations |
+| `ruff-format` | Code formatting (auto-fix) |
+| `pyright` | Static type checking (pylance engine) — config in `[tool.pyright]` in `pyproject.toml` |
+| `pytest` | Full test suite with ≥ 90% coverage |
+
+To run all hooks manually without committing:
+
+```bash
+pre-commit run --all-files
+```
+
+## Code style
+
+- **Formatter / linter:** ruff (`line-length = 120`, Python 3.10 target).
+- **Type hints:** all functions (public and private) must have complete PEP 484 type annotations. Enforced at lint time by ruff (`ANN` rules) and statically by pyright. `Any` is allowed for genuinely dynamic types; explicit `Any` is preferred over `object` when methods will be called on a value.
+- **Docstrings:** NumPy style for all public functions, classes, and modules.
+- **Comments:** only where the _why_ is non-obvious. No inline narration of what the code does.
+
+## Tests
+
+```bash
+pytest                                    # run all tests with coverage report
+pytest tests/emb/test_metrics.py         # run a specific file
+pytest tests/seg/                        # run a single subpackage
+pytest -k "test_purity"                   # run tests matching a pattern
+```
+
+Tests live in `tests/` and mirror the package structure. The coverage threshold (90%) is enforced both by `pytest` directly and by the pre-commit hook.
+
+## Pull requests
+
+- Keep PRs focused — one logical change per PR.
+- Write a clear description of what changed and why.
+- All pre-commit hooks must pass before requesting review.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the Apache License, Version 2.0.