tunarag-python 0.2.1__tar.gz

tunarag_python-0.2.1/.gitattributes

@@ -0,0 +1,7 @@
+* text=auto
+.gitattributes text eol=lf
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

tunarag_python-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.13"]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package and development tools
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+      - name: Check formatting
+        run: python -m ruff format --check .
+      - name: Lint
+        run: python -m ruff check .
+      - name: Type check
+        run: python -m mypy
+      - name: Test
+        run: python -m pytest
+      - name: Build distributions
+        run: python -m build
+      - name: Install built wheel
+        run: python -m pip install --force-reinstall --no-deps dist/tunarag_python-0.2.1-py3-none-any.whl
+      - name: Import built wheel
+        run: python -c "import tunarag; assert tunarag.__version__ == '0.2.1'"
+
+  framework-compatibility:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Install framework integrations
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev,frameworks]"
+      - name: Test real framework compatibility
+        run: python -m pytest tests/test_framework_compatibility.py

tunarag_python-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+name: Publish Python package
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Package index to publish to
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Validate distributions
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-testpypi:
+    if: inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/tunarag-python
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: inputs.target == 'pypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tunarag-python
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tunarag_python-0.2.1/.gitignore

@@ -0,0 +1,26 @@
+# Python bytecode and test/tool caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.tmp/
+.coverage
+htmlcov/
+
+# Local environments
+.venv/
+venv/
+env/
+
+# Build and distribution output
+build/
+dist/
+*.egg-info/
+
+# Local configuration and editor files
+.env
+.env.*
+.vscode/
+.idea/

tunarag_python-0.2.1/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to TunaRAG follow semantic versioning.
+
+## 0.2.1 - 2026-10-04
+
+### Added
+
+- Comprehensive product-first README with executable examples for every public workflow.
+- CI coverage that extracts and runs all 36 Python examples from the README.
+- Manual trusted-publishing workflow for separate TestPyPI and PyPI environments.
+
+### Fixed
+
+- Corrected dataset, LangGraph state, cache, resumability, optimizer-construction, and report-path
+  examples found through runtime documentation testing.
+- Replaced corrupted version-range punctuation in package metadata.
+
+## 0.2.0 - 2026-10-04
+
+### Added
+
+- Official `LangChainAdapter` for any asynchronous LangChain runnable.
+- Official `LangGraphAdapter` for compiled LangGraph graphs.
+- Default mapping from evaluation queries to `question` input and candidate parameters to the
+  framework `configurable` namespace.
+- Custom input, configuration, output, usage, and per-candidate runnable-factory hooks.
+- Automatic runnable latency and standard message token-usage capture.
+- Optional `langchain`, `langgraph`, and combined `frameworks` installation extras.
+- Real-framework compatibility tests against supported LangChain 1.x and LangGraph 1.x releases.
+
+## 0.1.0 - 2026-10-04
+
+### Added
+
+- Typed `RAGAdapter`, dataset, evaluator, search, objective, usage, callback, and result contracts.
+- Random and provider-neutral LLM search over arbitrary typed search spaces.
+- Async optimization with a safe synchronous wrapper, bounded concurrency, retry policies,
+  timeouts, caching, failure isolation, stopping rules, and resumable studies.
+- SQLite-first experiment storage with lifecycle events, recovery leases, and durable usage.
+- Canonical JSON/JSONL/CSV dataset ingestion, deterministic splitting, and synthetic QA support.
+- Optional lazy RAGAS evaluation and best-effort MLflow event mirroring.
+- Redacted JSON/CSV reports and a deterministic provider-free reference RAG quickstart.
+
+### Deferred
+
+- Formal Pareto-front reporting, Bayesian and grid search, distributed execution, a CLI, and
+  framework-specific LangChain/LlamaIndex adapters remain post-0.1 work.

tunarag_python-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+## Setup
+
+```powershell
+python -m venv .venv
+.venv\Scripts\python.exe -m pip install -e ".[dev]"
+```
+
+On macOS or Linux, activate `.venv` and use `python` in place of the Windows executable.
+
+## Change workflow
+
+1. Create a focused feature, fix, documentation, or chore branch from `main`.
+2. Update implementation, tests, and the living documents under `docs/` together.
+3. Run `python -m ruff format .`, `python -m ruff check .`, `python -m mypy`,
+   `python -m pytest`, and `python -m build`.
+4. Open a pull request with a concise summary and verification evidence.
+5. Merge only after the Linux and Windows CI matrix passes.
+
+Keep core dependencies provider-neutral. User code, provider calls, callbacks, and sleeps must
+not run inside SQLite transactions. New public behavior needs tests and API documentation;
+optional integrations must remain importable only when requested.

tunarag_python-0.2.1/DECISIONS.md

@@ -0,0 +1,88 @@
+# Decision Log
+
+The canonical living decision log is [`docs/decision.md`](docs/decision.md). This root file is
+retained for compatibility with existing links. New decisions belong in the canonical file.
+
+## Planning baseline
+
+### Use a Python-first library with async-first internals
+
+Decision: implement the core orchestration asynchronously and provide a synchronous convenience wrapper.
+
+Reasoning: RAG calls, evaluators, and provider calls are commonly I/O-bound; async orchestration supports timeouts, cancellation, and future concurrency while the wrapper keeps simple scripts approachable.
+
+### Keep the RAG application outside the package
+
+Decision: require a user-supplied `RAGAdapter` contract rather than prescribing a framework or owning the application pipeline.
+
+Reasoning: the package optimizes existing systems and must work across frameworks. This keeps the core portable and prevents the reference Auto-RAG-Research implementation from becoming a hidden dependency.
+
+### Make integrations optional
+
+Decision: keep RAGAS, MLflow, and provider-specific integrations behind optional dependency groups and import boundaries.
+
+Reasoning: the core evaluation, storage, and orchestration contracts should remain installable and testable without external services or heavyweight packages.
+
+### Use SQLite as the default source of durable state
+
+Decision: store studies, trials, attempts, metrics, usage, events, and recovery state in SQLite; treat MLflow as an optional mirror.
+
+Reasoning: SQLite is local, transactional, auditable, and sufficient for the V0.1 single-process scope. An external tracking service should not be required for correctness or resume.
+
+### Record exactness explicitly
+
+Decision: usage and aggregate reports distinguish exact, estimated, mixed, and unavailable values.
+
+Reasoning: unknown cost or latency must not silently become zero, and derived pricing must remain auditable. Budget policies can then state how estimates and unknowns affect scheduling.
+
+### Preserve secret safety as a cross-cutting invariant
+
+Decision: use redacted secret types, centralized canonical serialization, and explicit exclusions for secrets from hashes, logs, events, exports, cache metadata, and MLflow parameters.
+
+Reasoning: configuration and provider credentials cross many boundaries; local fixes at individual call sites are too easy to miss.
+
+### Begin with contracts and deterministic primitives
+
+Decision: the first feature branch delivers scaffolding, public models/contracts, canonical serialization, and tests before orchestration or integrations.
+
+Reasoning: the API specification and later persistence/search work depend on stable types and reproducible identity. Establishing those boundaries first reduces rework and makes each later branch reviewable.
+
+### Use `tunarag` as the import package name
+
+Decision: publish the distribution as `tunarag-python` and expose it through the `tunarag` Python import package.
+
+Reasoning: the repository/distribution name follows the requested project name while the shorter import name is idiomatic and leaves room for related tooling without a hyphenated module.
+
+### Use frozen dataclasses for core values
+
+Decision: represent the first domain values with frozen, slotted dataclasses and keep extension points as typing protocols.
+
+Reasoning: immutable values make trial identity and persistence safer, while protocols let callers implement adapters without adopting a package-specific model framework.
+
+### Exclude secret fields from canonical identity
+
+Decision: canonical mappings omit `Secret` values entirely and represent standalone secrets only with a redacted marker.
+
+Reasoning: credentials must never influence cache identity or appear in serialized bytes; nonsecret configuration remains stable and hashable.
+
+### Use package-owned random streams for V0.1 random search
+
+Decision: implement `RandomSearch` with an isolated `random.Random` instance owned by the strategy.
+
+Reasoning: a private seeded stream makes candidate sequences reproducible without mutating application-global random state or coupling search-space sampling to external frameworks.
+
+### Preserve value confidence during objective aggregation
+
+Decision: objective results carry `exact`, `estimated`, or `unavailable` status instead of converting missing or estimated values to zero.
+
+Reasoning: budget and ranking decisions must remain auditable; silently treating unknown values as exact would make optimization results misleading.
+
+### Use explicit SQLite transactions for lifecycle writes
+
+Decision: keep the first persistence layer on the standard-library `sqlite3` driver with explicit schema initialization and transaction scopes.
+
+Reasoning: V0.1 is single-process and local-first; direct transactions preserve lifecycle atomicity without adding an ORM before a second store backend exists.
+
+## Update rule
+
+Every important implementation choice records what was chosen, why it fits the design documents, and what alternative was rejected. Entries are added as decisions are made; this file is not a generic project diary.

tunarag_python-0.2.1/FLOW.md

@@ -0,0 +1,66 @@
+# Code Flow
+
+The canonical living code-flow document is [`docs/flow.md`](docs/flow.md). This root file is
+retained for compatibility with existing links. Update both the implementation and canonical
+flow document in the same feature branch.
+
+## Status
+
+V0.1 is implementation-complete. The canonical flow covers typed contracts, datasets and
+synthetic generation, RandomSearch and LLMSearch, objectives and stopping, SQLite storage and
+caching, retries and timeouts, bounded concurrency, callbacks, resumability, optional RAGAS and
+MLflow integrations, deterministic reporting, and the reference example.
+
+## Intended entry points
+
+- Public async study runner: accepts a study configuration, adapter, dataset, strategy, evaluator, objective, store, cache, and lifecycle policies.
+- Public synchronous convenience wrapper: runs the async entry point for ordinary scripts.
+- Public result/reporting APIs: load a completed or resumed study and expose ranked candidates, usage, budgets, and diagnostics.
+- Optional CLI or example entry points: demonstrate the library without becoming part of the core runtime contract.
+
+## Intended execution flow
+
+1. Resolve and validate configuration without persisting a wholesale environment snapshot.
+2. Open or create a SQLite-backed study and initialize schema/version metadata.
+3. Recover expired running attempts, apply retry policy, reconstruct budgets, and replay terminal observations when resuming.
+4. Ask the selected strategy for a typed candidate from the search space.
+5. Check the versioned cache using canonical candidate, dataset, evaluator, objective, and adapter identity parts.
+6. Execute the user-owned RAG adapter against the evaluation split with timeout and cancellation boundaries.
+7. Collect append-only usage records and exact/estimated/unavailable accounting.
+8. Run evaluation plugins and resolve objective metrics, normalization, direction, weights, and coverage requirements.
+9. Persist trial, metrics, usage, events, and cache data transactionally; emit callbacks/events without exposing secrets.
+10. Update strategy state, evaluate stop conditions and budgets, then continue or finalize.
+11. Return an actionable result with best candidates, tradeoffs, summaries, and recovery diagnostics.
+
+## Dependency flow
+
+Public models/contracts -> search/evaluation/objective/usage -> storage/cache -> orchestration -> optional integrations/examples.
+
+## Persistence flow
+
+Studies own ordered trials. Trials own attempts, candidate configurations, metrics, usage, and terminal events. Sequence numbers are monotonic and are never reused after recovery. Cache entries are independently versioned, checksummed, privacy-classified, and atomically written.
+
+## Recovery flow
+
+Load study and terminal observations, mark expired running attempts abandoned, apply retry policy, reconstruct exact and estimated budgets, initialize strategy state, replay observations, rebuild candidate hashes, continue sequence numbers, and emit a resume event with counts.
+
+## Current implemented flow
+
+The current optimization path resolves a new study, reserves candidates, checks the compatible
+evaluation cache, starts leased attempts, iterates the repeatable dataset, calls the adapter and
+evaluators under separate sample/trial deadlines, aggregates metrics, computes the objective,
+and atomically commits outcomes. Retryable failures persist attempt usage before deterministic
+backoff and a fresh attempt; exhausted failures remain isolated to their trial. Successful
+uncached metrics are cached only after the durable trial commit, while cache failures become
+events rather than trial failures. Resume validates the study configuration hash, rejects live
+leases, abandons only expired attempts in the selected study, rebuilds terminal summaries and
+usage, replays successful strategy observations, continues pending/recoverable trials, and
+persists the final stop reason. The sync wrappers reject an active event loop. Callback dispatch
+delivers newly committed events in sequence order, including retry scheduling before backoff;
+callback failures append redacted diagnostics without failing optimization. Bounded concurrency
+now schedules deterministic trial batches and independently bounded sample workers. Results and
+strategy observations are applied by durable trial sequence after each batch.
+
+## Update rule
+
+When an entry point, dependency, state transition, or persistence boundary is implemented, update this file in the same feature branch and commit as part of that feature.