tunarag-python 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
tunarag/__init__.py CHANGED
@@ -34,6 +34,7 @@ from .errors import (
34
34
  TunaRAGError,
35
35
  )
36
36
  from .evaluators import MetricEvaluator, MetricScorer, RagasEvaluator, RagasSampleMapper
37
+ from .integrations.google_adk import GoogleADKAdapter
37
38
  from .integrations.runnables import LangChainAdapter, LangGraphAdapter
38
39
  from .objective import Objective, ObjectiveDirection, ObjectiveResult, ObjectiveTerm
39
40
  from .result import OptimizationResult, TrialSummary, UsageSummary
@@ -103,6 +104,7 @@ __all__ = [
103
104
  "EvaluationDataset",
104
105
  "EvaluationExample",
105
106
  "FloatRange",
107
+ "GoogleADKAdapter",
106
108
  "InMemoryDataset",
107
109
  "IntegerRange",
108
110
  "LangChainAdapter",
@@ -163,4 +165,4 @@ __all__ = [
163
165
  "__version__",
164
166
  ]
165
167
 
166
- __version__ = "0.2.1"
168
+ __version__ = "0.3.0"
tunarag/contracts.py CHANGED
@@ -1,4 +1,4 @@
1
- """Protocols implemented by user-owned RAG systems and package extensions."""
1
+ """Internal pipeline boundary and public optimization extension protocols."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -12,14 +12,6 @@ if TYPE_CHECKING:
12
12
  from .store import StudyEvent
13
13
 
14
14
 
15
- class RAGAdapter(Protocol):
16
- """Execute a user's RAG system for one candidate and example."""
17
-
18
- async def run(
19
- self, candidate: Candidate, example: Any
20
- ) -> tuple[Any, Sequence[UsageRecord]]: ...
21
-
22
-
23
15
  class Dataset(Protocol):
24
16
  """Provide versioned evaluation examples."""
25
17
 
tunarag/engine.py CHANGED
@@ -18,12 +18,13 @@ from .contracts import (
18
18
  Evaluator,
19
19
  EventCallback,
20
20
  Fingerprintable,
21
- RAGAdapter,
22
21
  ReplayableSearchStrategy,
23
22
  SearchStrategy,
24
23
  )
25
24
  from .domain import Candidate, MetricValue, UsageRecord, ValueStatus
26
25
  from .errors import ResumeError, SearchSpaceError, SyncInAsyncContextError
26
+ from .integrations.google_adk import GoogleADKAdapter
27
+ from .integrations.runnables import LangChainAdapter, LangGraphAdapter
27
28
  from .objective import Objective, ObjectiveResult
28
29
  from .result import OptimizationResult, TrialSummary, UsageSummary
29
30
  from .retry import RetryPolicy
@@ -51,12 +52,12 @@ class _SampleResult:
51
52
 
52
53
 
53
54
  class Optimizer:
54
- """Coordinate V0.1 optimization trials through public contracts."""
55
+ """Tune pipelines through official LangChain, LangGraph, or Google ADK adapters."""
55
56
 
56
57
  def __init__(
57
58
  self,
58
59
  *,
59
- adapter: RAGAdapter,
60
+ adapter: LangChainAdapter | LangGraphAdapter | GoogleADKAdapter,
60
61
  strategy: SearchStrategy,
61
62
  evaluators: Sequence[Evaluator],
62
63
  objective: Objective,
@@ -70,6 +71,11 @@ class Optimizer:
70
71
  clock: Callable[[], float] = time.monotonic,
71
72
  duplicate_suggestion_limit: int = 100,
72
73
  ) -> None:
74
+ if not isinstance(adapter, (LangChainAdapter, LangGraphAdapter, GoogleADKAdapter)):
75
+ raise TypeError(
76
+ "optimizer requires LangChainAdapter, LangGraphAdapter, or GoogleADKAdapter; "
77
+ "custom RAG adapters are unsupported"
78
+ )
73
79
  if not evaluators:
74
80
  raise ValueError("optimizer requires at least one evaluator")
75
81
  if duplicate_suggestion_limit < 1:
@@ -300,7 +306,6 @@ class Optimizer:
300
306
  "cause": type(error).__name__,
301
307
  },
302
308
  )
303
- self._event_cursors[study_id] = self._latest_event_sequence(study_id)
304
309
 
305
310
  def _batch_capacity(self, summaries: Sequence[TrialSummary]) -> int:
306
311
  capacity = self._settings.concurrency
@@ -1,8 +1,8 @@
1
1
  """Optional integration adapters."""
2
2
 
3
+ from .google_adk import GoogleADKAdapter
3
4
  from .mlflow import MLflowCallback
4
5
  from .runnables import (
5
- AsyncRunnable,
6
6
  LangChainAdapter,
7
7
  LangGraphAdapter,
8
8
  RunnableConfigMapper,
@@ -13,7 +13,7 @@ from .runnables import (
13
13
  )
14
14
 
15
15
  __all__ = [
16
- "AsyncRunnable",
16
+ "GoogleADKAdapter",
17
17
  "LangChainAdapter",
18
18
  "LangGraphAdapter",
19
19
  "MLflowCallback",
@@ -0,0 +1,144 @@
1
+ """Google ADK 2.x runner integration with isolated evaluation sessions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ from collections.abc import Callable, Mapping
7
+ from importlib import import_module
8
+ from typing import Any
9
+ from uuid import uuid4
10
+
11
+ from ..domain import Candidate, UsageRecord
12
+ from ..errors import AdapterError, MissingOptionalDependencyError
13
+ from .runnables import _callable_identity, _token_count, _type_name
14
+
15
+
16
+ class GoogleADKAdapter:
17
+ """Evaluate a Google ADK runner in a fresh session for every sample and retry.
18
+
19
+ Candidate parameters become initial session state. Use a factory when changing
20
+ an agent's model, tools, or graph requires constructing a new framework runner.
21
+ """
22
+
23
+ def __init__(
24
+ self,
25
+ runner: Any = None,
26
+ *,
27
+ factory: Callable[[Candidate], Any] | None = None,
28
+ state_mapper: Callable[[Candidate], Mapping[str, Any]] | None = None,
29
+ output_mapper: Callable[[Any], Any] | None = None,
30
+ identity: Any = None,
31
+ ) -> None:
32
+ if (runner is None) == (factory is None):
33
+ raise ValueError("provide exactly one of runner or factory")
34
+ for name, callback in (
35
+ ("factory", factory),
36
+ ("state_mapper", state_mapper),
37
+ ("output_mapper", output_mapper),
38
+ ):
39
+ if callback is not None and not callable(callback):
40
+ raise TypeError(f"{name} must be callable")
41
+ if runner is not None:
42
+ _require_runner(runner)
43
+ self._runner = runner
44
+ self._factory = factory
45
+ self._state_mapper = state_mapper
46
+ self._output_mapper = output_mapper
47
+ self._identity = identity
48
+
49
+ async def run(self, candidate: Candidate, example: Any) -> tuple[Any, tuple[UsageRecord, ...]]:
50
+ """Consume runner events, capture usage, and remove the temporary session."""
51
+ runner = self._runner if self._factory is None else self._factory(candidate)
52
+ _require_runner(runner)
53
+ types = import_module("google.genai.types")
54
+ query = getattr(example, "query", example)
55
+ if not isinstance(query, str) or not query.strip():
56
+ raise TypeError("Google ADK evaluation input must contain a nonempty query")
57
+ state = (
58
+ dict(candidate.parameters)
59
+ if self._state_mapper is None
60
+ else self._state_mapper(candidate)
61
+ )
62
+ if not isinstance(state, Mapping):
63
+ raise TypeError("state_mapper must return a mapping")
64
+ session_id = uuid4().hex
65
+ user_id = "tunarag-evaluation"
66
+ session = await runner.session_service.create_session(
67
+ app_name=runner.app_name,
68
+ user_id=user_id,
69
+ session_id=session_id,
70
+ state=dict(state),
71
+ )
72
+ usage: list[UsageRecord] = []
73
+ final_event = None
74
+ started_at = time.perf_counter()
75
+ events = runner.run_async(
76
+ user_id=user_id,
77
+ session_id=session.id,
78
+ new_message=types.Content(role="user", parts=[types.Part.from_text(text=query)]),
79
+ )
80
+ try:
81
+ async for event in events:
82
+ if event.error_code:
83
+ raise AdapterError("Google ADK runner returned an error event", stage="adapter")
84
+ metadata = event.usage_metadata
85
+ if metadata is not None:
86
+ usage.append(
87
+ UsageRecord(
88
+ "google_adk.model",
89
+ input_tokens=_token_count(metadata.prompt_token_count),
90
+ output_tokens=_token_count(metadata.candidates_token_count),
91
+ )
92
+ )
93
+ if event.is_final_response():
94
+ final_event = event
95
+ if final_event is None:
96
+ raise AdapterError("Google ADK runner produced no final response", stage="adapter")
97
+ if self._output_mapper is None and final_event.content is None:
98
+ raise AdapterError(
99
+ "ADK final event has no text; provide output_mapper for structured output",
100
+ stage="adapter",
101
+ )
102
+ output = (
103
+ self._output_mapper(final_event)
104
+ if self._output_mapper is not None
105
+ else {
106
+ "answer": "".join(
107
+ part.text or ""
108
+ for part in final_event.content.parts or ()
109
+ if not part.thought
110
+ )
111
+ }
112
+ )
113
+ usage.append(
114
+ UsageRecord("google_adk.runner", latency_seconds=time.perf_counter() - started_at)
115
+ )
116
+ return output, tuple(usage)
117
+ finally:
118
+ try:
119
+ await events.aclose()
120
+ finally:
121
+ await runner.session_service.delete_session(
122
+ app_name=runner.app_name, user_id=user_id, session_id=session.id
123
+ )
124
+
125
+ def fingerprint(self) -> dict[str, Any]:
126
+ """Describe integration semantics without sessions or provider credentials."""
127
+ return {
128
+ "integration": "google_adk",
129
+ "schema_version": 1,
130
+ "runner": _type_name(self._runner) if self._runner is not None else None,
131
+ "factory": _callable_identity(self._factory),
132
+ "state_mapper": _callable_identity(self._state_mapper),
133
+ "output_mapper": _callable_identity(self._output_mapper),
134
+ "identity": self._identity,
135
+ }
136
+
137
+
138
+ def _require_runner(value: Any) -> None:
139
+ try:
140
+ runner_type = import_module("google.adk.runners").Runner
141
+ except ImportError as error:
142
+ raise MissingOptionalDependencyError("Google ADK", "google-adk") from error
143
+ if not isinstance(value, runner_type):
144
+ raise TypeError("GoogleADKAdapter requires a real Google ADK Runner")
@@ -5,22 +5,12 @@ from __future__ import annotations
5
5
  import inspect
6
6
  import time
7
7
  from collections.abc import Callable, Mapping, Sequence
8
- from typing import Any, Protocol
8
+ from importlib import import_module
9
+ from typing import Any
9
10
 
10
11
  from ..dataset import EvaluationExample
11
12
  from ..domain import Candidate, UsageRecord
12
-
13
-
14
- class AsyncRunnable(Protocol):
15
- """Shared asynchronous invocation surface implemented by both frameworks."""
16
-
17
- async def ainvoke(
18
- self,
19
- input: Any,
20
- config: Any = None,
21
- **kwargs: Any,
22
- ) -> Any: ...
23
-
13
+ from ..errors import MissingOptionalDependencyError
24
14
 
25
15
  RunnableFactory = Callable[[Candidate], Any]
26
16
  RunnableInputMapper = Callable[[Any, Candidate], Any]
@@ -47,7 +37,7 @@ class _RunnableAdapter:
47
37
  if (runnable is None) == (factory is None):
48
38
  raise ValueError("provide exactly one of runnable or factory")
49
39
  if runnable is not None:
50
- _require_runnable(runnable)
40
+ _require_runnable(runnable, framework)
51
41
  if factory is not None and not callable(factory):
52
42
  raise TypeError("runnable factory must be callable")
53
43
  if not input_key.strip():
@@ -116,7 +106,7 @@ class _RunnableAdapter:
116
106
  if self._factory is None:
117
107
  raise RuntimeError("runnable adapter is not configured")
118
108
  runnable = self._factory(candidate)
119
- _require_runnable(runnable)
109
+ _require_runnable(runnable, self._framework)
120
110
  return runnable
121
111
 
122
112
  def _map_input(self, example: Any, candidate: Candidate) -> Any:
@@ -251,10 +241,20 @@ def _token_count(value: Any) -> int | None:
251
241
  return value
252
242
 
253
243
 
254
- def _require_runnable(value: Any) -> None:
255
- method = getattr(value, "ainvoke", None)
256
- if method is None or not callable(method):
257
- raise TypeError("framework object must provide an async ainvoke method")
244
+ def _require_runnable(value: Any, framework: str) -> None:
245
+ module, name = (
246
+ ("langchain_core.runnables", "Runnable")
247
+ if framework == "langchain"
248
+ else ("langgraph.graph.state", "CompiledStateGraph")
249
+ )
250
+ try:
251
+ framework_type = getattr(import_module(module), name)
252
+ except ImportError as error:
253
+ raise MissingOptionalDependencyError(framework, framework) from error
254
+ if not isinstance(value, framework_type):
255
+ raise TypeError(
256
+ f"{framework} integration requires a real {name}, not a custom ainvoke object"
257
+ )
258
258
 
259
259
 
260
260
  def _callable_identity(value: Callable[..., Any] | None) -> str | None:
tunarag/search.py CHANGED
@@ -147,6 +147,7 @@ class RandomSearch:
147
147
  self._space = space
148
148
  self._seed = seed
149
149
  self._generator = random.Random(seed)
150
+ self._replayed_candidates: list[Candidate] = []
150
151
 
151
152
  async def suggest(self) -> Candidate:
152
153
  return self._space.sample(self._generator)
@@ -158,9 +159,16 @@ class RandomSearch:
158
159
  """Advance and verify deterministic generator state during resume."""
159
160
 
160
161
  del metrics, usage
161
- expected = self._space.sample(self._generator)
162
- if expected != candidate:
162
+ if candidate in self._replayed_candidates:
163
163
  raise ValueError("persisted candidate does not match seeded random search state")
164
+ for _ in range(10_000):
165
+ expected = self._space.sample(self._generator)
166
+ if expected == candidate:
167
+ self._replayed_candidates.append(candidate)
168
+ return
169
+ if expected not in self._replayed_candidates:
170
+ break
171
+ raise ValueError("persisted candidate does not match seeded random search state")
164
172
 
165
173
  def fingerprint(self) -> Any:
166
174
  """Return stable search-space and seed semantics."""
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: tunarag-python
3
- Version: 0.2.1
4
- Summary: Typed, durable optimization workflows for existing RAG systems
3
+ Version: 0.3.0
4
+ Summary: Tune LangChain, LangGraph, and Google ADK RAG pipelines
5
5
  Project-URL: Repository, https://github.com/shivamshinde123/tunarag-python
6
6
  Project-URL: Issues, https://github.com/shivamshinde123/tunarag-python/issues
7
7
  Project-URL: Changelog, https://github.com/shivamshinde123/tunarag-python/blob/main/CHANGELOG.md
@@ -23,20 +23,48 @@ Requires-Dist: tomli>=2.0; python_version < '3.11'
23
23
  Provides-Extra: dev
24
24
  Requires-Dist: build>=1.2; extra == 'dev'
25
25
  Requires-Dist: hypothesis>=6.100; extra == 'dev'
26
+ Requires-Dist: langchain-classic<2,>=1; extra == 'dev'
27
+ Requires-Dist: langchain-core<2,>=1; extra == 'dev'
28
+ Requires-Dist: langgraph<2,>=1; extra == 'dev'
26
29
  Requires-Dist: mypy>=1.11; extra == 'dev'
30
+ Requires-Dist: numpy<3,>=1.26; extra == 'dev'
27
31
  Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
28
32
  Requires-Dist: pytest>=8.0; extra == 'dev'
29
33
  Requires-Dist: ruff>=0.6; extra == 'dev'
34
+ Provides-Extra: docs
35
+ Requires-Dist: mkdocs-include-markdown-plugin<8,>=7; extra == 'docs'
36
+ Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
37
+ Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
38
+ Requires-Dist: mkdocstrings[python]<1,>=0.27; extra == 'docs'
30
39
  Provides-Extra: frameworks
40
+ Requires-Dist: google-adk<3,>=2; extra == 'frameworks'
31
41
  Requires-Dist: langchain<2,>=1; extra == 'frameworks'
32
42
  Requires-Dist: langgraph<2,>=1; extra == 'frameworks'
43
+ Requires-Dist: numpy<3,>=1.26; extra == 'frameworks'
44
+ Provides-Extra: google-adk
45
+ Requires-Dist: google-adk<3,>=2; extra == 'google-adk'
33
46
  Provides-Extra: langchain
34
47
  Requires-Dist: langchain<2,>=1; extra == 'langchain'
48
+ Requires-Dist: numpy<3,>=1.26; extra == 'langchain'
35
49
  Provides-Extra: langgraph
36
50
  Requires-Dist: langgraph<2,>=1; extra == 'langgraph'
51
+ Provides-Extra: live-adk-test
52
+ Requires-Dist: google-adk<3,>=2.11; extra == 'live-adk-test'
53
+ Requires-Dist: litellm<2,>=1.104; extra == 'live-adk-test'
54
+ Provides-Extra: live-test
55
+ Requires-Dist: langchain-classic<2,>=1; extra == 'live-test'
56
+ Requires-Dist: langchain-community<0.4,>=0.3.31; extra == 'live-test'
57
+ Requires-Dist: langchain-openai<2,>=1; extra == 'live-test'
58
+ Requires-Dist: langgraph<2,>=1; extra == 'live-test'
59
+ Requires-Dist: mlflow<4,>=3; extra == 'live-test'
60
+ Requires-Dist: pypdf<7,>=5; extra == 'live-test'
61
+ Requires-Dist: pytest>=8; extra == 'live-test'
62
+ Requires-Dist: python-dotenv<2,>=1; extra == 'live-test'
63
+ Requires-Dist: ragas<0.5,>=0.4; extra == 'live-test'
37
64
  Provides-Extra: mlflow
38
65
  Requires-Dist: mlflow<4,>=3; extra == 'mlflow'
39
66
  Provides-Extra: ragas
67
+ Requires-Dist: langchain-community<0.4,>=0.3.31; extra == 'ragas'
40
68
  Requires-Dist: ragas<0.5,>=0.4; extra == 'ragas'
41
69
  Description-Content-Type: text/markdown
42
70
 
@@ -58,7 +86,7 @@ isolates failures, supports resumable execution, and produces results you can in
58
86
  - Compare configurations with custom metrics or optional RAGAS evaluators.
59
87
  - Optimize a weighted objective across quality, provider cost, and response latency.
60
88
  - Search with deterministic random search or provider-neutral LLM-guided search.
61
- - Tune existing custom, LangChain, or LangGraph RAG pipelines without rebuilding them.
89
+ - Tune LangChain, LangGraph, or Google ADK RAG pipelines without rebuilding them.
62
90
  - Preserve reproducible experiments with caching, retries, callbacks, reports, and SQLite resume.
63
91
 
64
92
  ### Who is it for?
@@ -70,9 +98,30 @@ indexes, provider clients, and credentials; TunaRAG owns the optimization workfl
70
98
  > Install the distribution as `tunarag-python` and import it as `tunarag`. Python 3.10-3.13 is
71
99
  > supported.
72
100
 
101
+ **Documentation:** [shivamshinde123.github.io/tunarag-python](https://shivamshinde123.github.io/tunarag-python/)
102
+
103
+ **Lightweight distribution:** pip installs runtime code and metadata, not tests, datasets,
104
+ or documentation images. Framework dependencies are optional extras. See
105
+ [package contents and release checks](docs/package-distribution.md).
106
+
107
+ **Live integration checks:** [OpenRouter, RAGAS, and MLflow test plan](docs/live-integration-test-plan.md).
108
+
109
+ **End-to-end verification:** [Full-PDF campaigns, held-out quality checks, crash recovery,
110
+ and clean-wheel testing](docs/comprehensive-testing.md). Paid tests are explicit opt-ins;
111
+ ordinary CI never makes paid provider calls.
112
+ These opt-in tests include spending safeguards; normal tests never make paid calls.
113
+
114
+ **Google ADK validation:** [Real OpenRouter RAG tuning, RAGAS scoring, SQLite resume,
115
+ and MLflow checks](docs/live-google-adk-testing.md).
116
+
117
+ **Quality and reliability:** [Ordered validation plan](docs/quality-validation-plan.md)
118
+ and [bounded repeated tuning, ADK tools, billing and recovery checks](docs/reliability-validation.md).
119
+ See [mixed-topic validation](docs/multicorpus-validation.md) for cross-model QA,
120
+ simulated faults/load, and the unresolved adversarial-prompt failure.
121
+
73
122
  ## Comprehensive Usage Guide
74
123
 
75
- The sections below explain every public TunaRAG Python V0.2 feature with executable examples.
124
+ The sections below explain every public TunaRAG Python V0.3 feature with executable examples.
76
125
 
77
126
  ## Contents
78
127
 
@@ -124,6 +173,8 @@ A **study** contains ordered **trials**. Each trial evaluates one complete candi
124
173
  against every dataset example. Same-named sample metrics are aggregated into trial metrics, then the
125
174
  objective converts those metrics into one larger-is-better score.
126
175
 
176
+ ![A hand-drawn Xiaohei operating TunaRAG's iterative optimization loop](docs/assets/tunarag-python-readme-illustrations/01-optimization-loop.png)
177
+
127
178
  TunaRAG does not create or host a RAG application, provision indexes, manage provider credentials,
128
179
  or expose a hosted API. Your application keeps ownership of those concerns.
129
180
 
@@ -137,141 +188,140 @@ python -m pip install tunarag-python
137
188
  |---|---|
138
189
  | LangChain | `python -m pip install "tunarag-python[langchain]"` |
139
190
  | LangGraph | `python -m pip install "tunarag-python[langgraph]"` |
140
- | Both frameworks | `python -m pip install "tunarag-python[frameworks]"` |
191
+ | LangChain and LangGraph; ADK on Python 3.10+ | `python -m pip install "tunarag-python[frameworks]"` |
192
+ | Google ADK 2.x (Python 3.10+) | `python -m pip install "tunarag-python[google-adk]"` |
141
193
  | RAGAS | `python -m pip install "tunarag-python[ragas]"` |
142
194
  | MLflow | `python -m pip install "tunarag-python[mlflow]"` |
143
195
 
144
- Optional dependencies load lazily; the core package does not require them.
196
+ Framework dependencies load lazily. Install the extra for your pipeline before constructing its adapter. Google ADK requires Python 3.10 or newer; LangChain and LangGraph retain Python 3.10 support.
145
197
 
146
198
  ## End-to-end quickstart
147
199
 
148
- This deterministic example shows the complete public workflow without external providers.
200
+ Use an installed framework integration. The offline quickstart uses LangChain's vector store,
201
+ retriever, prompt, and fake model; the provider-backed example uses OpenRouter. Fake embeddings and
202
+ the fake model test wiring only; their scores do not demonstrate retrieval or answer quality.
149
203
 
150
204
  ```python
205
+ from pathlib import Path
206
+
207
+ from langchain_core.documents import Document
208
+ from langchain_core.embeddings import DeterministicFakeEmbedding
209
+ from langchain_core.language_models.fake import FakeListLLM
210
+ from langchain_core.prompts import ChatPromptTemplate
211
+ from langchain_core.runnables import RunnablePassthrough
212
+ from langchain_core.vectorstores import InMemoryVectorStore
151
213
  from tunarag import (
152
214
  EvaluationDataset,
153
215
  IntegerRange,
216
+ LangChainAdapter,
154
217
  MetricEvaluator,
155
218
  Objective,
156
219
  ObjectiveTerm,
157
220
  Optimizer,
158
221
  RandomSearch,
159
222
  SearchSpace,
160
- UsageRecord,
161
223
  )
162
224
 
163
- DOCUMENTS = {
164
- "python": "Python is a high-level programming language.",
165
- "sqlite": "SQLite is a local embedded relational database.",
166
- "rag": "RAG combines retrieval with generation.",
167
- }
168
-
169
-
170
- class SmallRAG:
171
- async def run(self, candidate, example):
172
- query_words = set(example.query.lower().split())
173
- ranked = sorted(
174
- DOCUMENTS.values(),
175
- key=lambda text: len(query_words & set(text.lower().split())),
176
- reverse=True,
177
- )
178
- contexts = ranked[: candidate.parameters["top_k"]]
179
- return {"answer": " ".join(contexts)}, (UsageRecord("small-rag", latency_seconds=0.001),)
225
+ vector_store = InMemoryVectorStore.from_documents(
226
+ [
227
+ Document(page_content="SQLite stores local experiments."),
228
+ Document(page_content="TunaRAG compares RAG configurations."),
229
+ ],
230
+ DeterministicFakeEmbedding(size=32),
231
+ )
232
+ prompt = ChatPromptTemplate.from_template("Context: {context}\nQuestion: {question}")
180
233
 
181
234
 
182
- def answer_recall(output, example):
183
- expected = set(example.reference_answer.lower().split())
184
- actual = set(output["answer"].lower().split())
185
- return len(expected & actual) / len(expected)
235
+ def build_chain(candidate):
236
+ retriever = vector_store.as_retriever(search_kwargs={"k": candidate.parameters["top_k"]})
237
+ return {"context": retriever, "question": RunnablePassthrough()} | RunnablePassthrough.assign(
238
+ answer=prompt | FakeListLLM(responses=["SQLite stores local experiments."])
239
+ )
186
240
 
187
241
 
188
242
  dataset = EvaluationDataset.from_records(
189
243
  [
190
244
  {
191
245
  "id": "q1",
192
- "query": "What is SQLite?",
193
- "reference_answer": "a local embedded relational database",
194
- },
195
- {
196
- "id": "q2",
197
- "query": "What does RAG combine?",
198
- "reference_answer": "retrieval with generation",
199
- },
246
+ "query": "What stores experiments and compares configurations?",
247
+ "reference_answer": "SQLite and TunaRAG",
248
+ "reference_contexts": [
249
+ "SQLite stores local experiments.",
250
+ "TunaRAG compares RAG configurations.",
251
+ ],
252
+ }
200
253
  ]
201
254
  )
202
255
  optimizer = Optimizer(
203
- adapter=SmallRAG(),
204
- strategy=RandomSearch(SearchSpace({"top_k": IntegerRange(1, 3)}), seed=7),
205
- evaluators=(MetricEvaluator("answer_recall", answer_recall),),
206
- objective=Objective((ObjectiveTerm("answer_recall"),)),
256
+ adapter=LangChainAdapter(
257
+ factory=build_chain, input_mapper=lambda example, candidate: example.query
258
+ ),
259
+ strategy=RandomSearch(SearchSpace({"top_k": IntegerRange(1, 2)}), seed=7),
260
+ evaluators=(
261
+ MetricEvaluator(
262
+ "retrieval_recall",
263
+ lambda output, example: (
264
+ len(
265
+ {document.page_content for document in output["context"]}
266
+ & set(example.reference_contexts)
267
+ )
268
+ / len(example.reference_contexts)
269
+ ),
270
+ ),
271
+ ),
272
+ objective=Objective((ObjectiveTerm("retrieval_recall"),)),
207
273
  )
208
274
  try:
209
- result = optimizer.optimize(dataset, study_name="small-rag")
275
+ result = optimizer.optimize(dataset, study_name="langchain-rag")
210
276
  print(result.best_candidate.parameters if result.best_candidate else "no winner")
211
277
  finally:
212
278
  optimizer.close()
213
279
  ```
214
280
 
215
281
  The default store is in memory. Use `SQLiteStore(path)` for a durable study.
282
+ Here `top_k=1` retrieves one of two required contexts (recall `0.5`); `top_k=2` retrieves both
283
+ (recall `1.0`), so tuning selects `top_k=2`. This verifies parameter application and ranking with
284
+ offline framework components; it does not benchmark a real embedding model or generated answer.
216
285
 
217
286
  ## RAG adapters
218
287
 
219
- A custom adapter implements:
288
+ Choose an official adapter: `LangChainAdapter`, `LangGraphAdapter`, or `GoogleADKAdapter`.
289
+ The optimizer rejects handwritten `run` adapters. LangChain accepts genuine framework `Runnable`
290
+ objects; LangGraph accepts `CompiledStateGraph`; Google ADK accepts `Runner`. Factory results are
291
+ validated on every sample, and failures enter the normal trial failure and retry boundary.
220
292
 
221
293
  ```python
222
- from collections.abc import Sequence
223
-
224
- from tunarag import UsageRecord
225
-
294
+ from langchain_core.runnables import RunnableLambda
295
+ from tunarag import LangChainAdapter
226
296
 
227
- async def run(candidate, example) -> tuple[object, Sequence[UsageRecord]]: ...
297
+ chain = RunnableLambda(lambda inputs: {"answer": inputs["question"]})
298
+ adapter = LangChainAdapter(chain)
228
299
  ```
229
300
 
230
- `candidate.parameters` contains the proposed configuration. The output can be any object understood
231
- by your evaluators. Usage may be empty. Adapter exceptions enter TunaRAG's retry and trial-failure
232
- boundary.
233
-
234
- ```python
235
- from tunarag import UsageRecord, ValueStatus
301
+ ![A hand-drawn Xiaohei connecting a framework RAG pipeline through TunaRAG](docs/assets/tunarag-python-readme-illustrations/02-rag-adapter-boundary.png)
236
302
 
303
+ Candidate parameters go into framework configuration or initial ADK session state. A parameter
304
+ only changes behavior if the framework consumes it. For model, prompt, retriever, or index choices
305
+ that require rebuilding the pipeline, use a per-candidate framework factory. Mapping callbacks
306
+ adapt framework inputs and outputs; they do not require implementing a RAG adapter.
237
307
 
238
- class ExistingRAGAdapter:
239
- def __init__(self, service):
240
- self.service = service
241
-
242
- async def run(self, candidate, example):
243
- response = await self.service.answer(
244
- query=example.query,
245
- top_k=candidate.parameters["top_k"],
246
- model=candidate.parameters["model"],
247
- )
248
- return response, (
249
- UsageRecord(
250
- component="generator",
251
- input_tokens=response.input_tokens,
252
- output_tokens=response.output_tokens,
253
- cost=response.cost,
254
- latency_seconds=response.latency_seconds,
255
- status=ValueStatus.EXACT,
256
- pricing_version="provider-2026-10",
257
- ),
258
- )
308
+ ```python
309
+ from langchain_core.runnables import RunnableLambda
310
+ from tunarag import LangChainAdapter
259
311
 
260
- def fingerprint(self):
261
- return {
262
- "adapter_version": 2,
263
- "index_revision": "docs-2026-10-04",
264
- "prompt_revision": "qa-v3",
265
- }
312
+ adapter = LangChainAdapter(
313
+ RunnableLambda(lambda inputs: {"answer": inputs["question"]}),
314
+ identity={"index_revision": "docs-v1", "prompt_revision": "qa-v1"},
315
+ )
266
316
  ```
267
317
 
268
- Use `ValueStatus.ESTIMATED` for inferred usage and `UNAVAILABLE` when it cannot be determined.
269
- Implement `fingerprint()` when class identity alone does not represent semantics. Fingerprints affect
270
- cache and resume compatibility; include stable versions, never credentials.
318
+ Include stable corpus, index, model, prompt, and mapper revisions in `identity` for cache and resume
319
+ compatibility. Never include credentials. Framework factories and mapping callbacks remain normal
320
+ Python configuration code; retrieval and generation execute through the framework.
271
321
 
272
322
  ## LangChain integration
273
323
 
274
- `LangChainAdapter` accepts any asynchronous runnable with `ainvoke(input, config=...)`.
324
+ `LangChainAdapter` accepts a real LangChain `Runnable` with `ainvoke(input, config=...)`.
275
325
 
276
326
  ```python
277
327
  from langchain_core.runnables import RunnableLambda
@@ -307,11 +357,16 @@ def build_chain(candidate):
307
357
 
308
358
  adapter = LangChainAdapter(
309
359
  factory=build_chain,
360
+ input_key="input",
310
361
  output_mapper=lambda output: output["answer"],
311
362
  identity={"factory_schema": 1},
312
363
  )
313
364
  ```
314
365
 
366
+ This factory fragment assumes `vector_store` and `build_qa_chain(model)` already exist. The
367
+ standard `create_retrieval_chain` requires the `input` key and comes from `langchain-classic`;
368
+ install that package and import it before using this fragment.
369
+
315
370
  Customize all boundaries when required:
316
371
 
317
372
  ```python
@@ -341,6 +396,12 @@ and message objects. The adapter always adds `langchain.runnable` latency. Set
341
396
  `capture_message_usage=False` to disable automatic token extraction. A custom `usage_mapper` takes
342
397
  precedence.
343
398
 
399
+ For a complete provider-backed pipeline—from documents and embeddings through optimization and
400
+ reports—run
401
+ [`examples/langchain_full_rag.py`](https://github.com/shivamshinde123/tunarag-python/blob/main/examples/langchain_full_rag.py).
402
+ The example loads `OPENROUTER_API_KEY` from a repository-root `.env` file and uses OpenRouter for
403
+ both chat generation and embeddings; copy `.env.example` to `.env` to get started.
404
+
344
405
  ## LangGraph integration
345
406
 
346
407
  `LangGraphAdapter` has the same factory and mapping options.
@@ -392,8 +453,27 @@ adapter = LangGraphAdapter(
392
453
  The adapter always adds `langgraph.runnable` latency. Framework errors remain visible to the engine's
393
454
  retry and failure handling.
394
455
 
456
+ ## Google ADK integration
457
+
458
+ Install `tunarag-python[google-adk]` on Python 3.10+. `GoogleADKAdapter(runner)` accepts a real ADK
459
+ 2.x `Runner` or `InMemoryRunner`. Candidate parameters become initial session state. Each sample
460
+ and retry gets a fresh session, which is removed after success, failure, or cancellation. Providers,
461
+ agent tools, corpus retrieval, and runner ownership remain with the application.
462
+
463
+ Use `factory=lambda candidate: build_runner(candidate)` when tuning settings such as a model or
464
+ retrieval tool that require constructing an agent. `state_mapper` can map candidates to agent state;
465
+ `output_mapper` receives the final ADK event, allowing retrieval evidence to be exposed for RAGAS.
466
+ By default the output is `{"answer": final_text}`. Usage captures reported model token counts and
467
+ runner latency; dollar cost is unavailable unless your evaluator supplies a priced metric.
468
+ Missing final responses and ADK error events fail the trial rather than becoming empty answers.
469
+
470
+ See the executable [ADK example](https://github.com/shivamshinde123/tunarag-python/blob/main/examples/google_adk_tuning.py)
471
+ and [integration reference](https://github.com/shivamshinde123/tunarag-python/blob/main/docs/reference/integrations.md).
472
+
395
473
  ## Evaluation datasets
396
474
 
475
+ ![A hand-drawn Xiaohei normalizing, validating, hashing, and splitting evaluation records](docs/assets/tunarag-python-readme-illustrations/03-dataset-preparation.png)
476
+
397
477
  ### Canonical model
398
478
 
399
479
  ```python
@@ -528,6 +608,8 @@ using them as gold data. Generation usage is separate from optimization usage.
528
608
 
529
609
  ## Search spaces and strategies
530
610
 
611
+ ![A hand-drawn Xiaohei validating candidates from RandomSearch and LLMSearch](docs/assets/tunarag-python-readme-illustrations/04-search-strategies.png)
612
+
531
613
  ### Typed space
532
614
 
533
615
  ```python
@@ -903,6 +985,8 @@ labels are metadata, not encryption.
903
985
 
904
986
  ## SQLite persistence and resume
905
987
 
988
+ ![A hand-drawn Xiaohei recovering and resuming a committed SQLite study after interruption](docs/assets/tunarag-python-readme-illustrations/05-persistence-and-resume.png)
989
+
906
990
  ```python
907
991
  from pathlib import Path
908
992
 
@@ -1000,6 +1084,8 @@ reconciliation is not included in V0.2.
1000
1084
 
1001
1085
  ## Results and reports
1002
1086
 
1087
+ ![A hand-drawn Xiaohei balancing quality, cost, and latency before exporting the winning result](docs/assets/tunarag-python-readme-illustrations/06-results-and-reports.png)
1088
+
1003
1089
  `OptimizationResult` exposes:
1004
1090
 
1005
1091
  ```python
@@ -1082,7 +1168,7 @@ Protocols are structural; inheritance is not required.
1082
1168
 
1083
1169
  | Contract | Required behavior |
1084
1170
  |---|---|
1085
- | `RAGAdapter` | `async run(candidate, example) -> (output, usage)` |
1171
+ | Official framework adapters | `LangChainAdapter`, `LangGraphAdapter`, `GoogleADKAdapter` |
1086
1172
  | `Dataset` | `.version` and async iteration |
1087
1173
  | `Evaluator` | `async evaluate(output, example) -> metrics` |
1088
1174
  | `SearchStrategy` | `async suggest()` and `async observe(...)` |
@@ -1126,7 +1212,7 @@ Provider descriptions and component fingerprints must not expose secrets.
1126
1212
 
1127
1213
  - Use a file-backed `SQLiteStore` and back it up.
1128
1214
  - Keep a human-reviewed test split outside optimization.
1129
- - Fingerprint custom adapters and evaluators.
1215
+ - Supply framework pipeline revisions through adapter `identity` and fingerprint custom evaluators.
1130
1216
  - Include a hard stopping bound and conservative concurrency.
1131
1217
  - Track exact usage when available and label estimates.
1132
1218
  - Configure sample and trial timeouts.
@@ -1142,7 +1228,7 @@ Provider descriptions and component fingerprints must not expose secrets.
1142
1228
  V0.2 does not provide a hosted service/dashboard, automatic RAG construction, vector-database
1143
1229
  provisioning, distributed workers, Pareto optimization, Bayesian/evolutionary search, encrypted
1144
1230
  payloads, MLflow reconciliation, provider pricing management, or a TypeScript implementation.
1145
- LangChain and LangGraph are official integrations; other frameworks use `RAGAdapter`.
1231
+ LangChain, LangGraph, and Google ADK 2.x are official integrations. Additional frameworks require a future first-party integration; custom RAG adapters are unsupported.
1146
1232
 
1147
1233
  | Term | Meaning |
1148
1234
  |---|---|
@@ -1,24 +1,25 @@
1
- tunarag/__init__.py,sha256=v2u4rhSU4Q0QG8T59iGJbAyTLPvQjP7IOQJ6CnpwvzU,3617
1
+ tunarag/__init__.py,sha256=RlM5mZYGfa6ZsvmYY3xJCd9MRCRr3vMUqgC3DmaxmuI,3695
2
2
  tunarag/cache.py,sha256=prra0uAjW1JYVez6nA9xXFnRwANODHo1rj6o1EiGLI8,11556
3
3
  tunarag/config.py,sha256=EzoRWhViL4OQRMFadhiNwEwvne64p2XYMgigaV4tDqg,9325
4
- tunarag/contracts.py,sha256=Qr_kfMLas2MaBbuvhlOVLkezKLxDej3th6OodLaSRfA,2289
4
+ tunarag/contracts.py,sha256=H3rpzKJjN9F34t6ukJj4q7iBrOjFa9PzOwLk-s8A_Pk,2073
5
5
  tunarag/dataset.py,sha256=IPFepM9TOOMREZRUOr4XJdQCrSnXrA8PHVpmKiDa-8I,18111
6
6
  tunarag/domain.py,sha256=7bGGb_lHiWQQEMF2bohwMJvrCvslhj-9h5CAKtLd2-A,2663
7
- tunarag/engine.py,sha256=JejhlwwkIR93cBTxpA5hO4By7vFeYkEUueRDvWwXfUw,40560
7
+ tunarag/engine.py,sha256=ceotkoHaL0OX5MAuHHGpuFg92tVDeMx9C0stQA-aR2M,40931
8
8
  tunarag/errors.py,sha256=cB6gZ6txDRPdKcwXmWvEL_7mUcooQdUIrW5qyxBQM9Q,5196
9
9
  tunarag/evaluators.py,sha256=BRhreWBEUeu2WU2TTwHqZnhopGA76Ou16T83X9zxuhw,7306
10
10
  tunarag/objective.py,sha256=VZ2M_km5bVbsMbzow7LcMl88dO6b_wB5-JIlk3pnMC8,2785
11
11
  tunarag/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
12
12
  tunarag/result.py,sha256=K-zI5Zr1uG_Q295YgE0buWSrWMeEMnQEAaVp5QUYnws,10468
13
13
  tunarag/retry.py,sha256=buxAMa9AuYCFvg2GxhHDQbFco3UExVdyBYuLHQaj_ck,2682
14
- tunarag/search.py,sha256=h8XJLJ0dGJN-GuURum_osUFx9MvQMUdt3-nLq9gxxwU,9875
14
+ tunarag/search.py,sha256=E0co3arc__ExCsB5q0NYPtiODjGiKdBgIPqju4fJpIs,10275
15
15
  tunarag/serialization.py,sha256=c4KyCVc6z47OzTqy96FVeG1Jfkvcxxy0sdZ9X-I8-M0,2870
16
16
  tunarag/stopping.py,sha256=0MkFD4rHFbwq_I8qq7bv770Aii5JLvYDuqXIXL8dKB4,6899
17
17
  tunarag/store.py,sha256=_d2z315K-FwZt8obmdLmfS5O8zpHEEXyWDzwZrnVw_c,36281
18
18
  tunarag/synthetic.py,sha256=TOSpOTTSEMvbtWcK0R1we5dXkJNxEGBuzkU6C5djaM0,9860
19
- tunarag/integrations/__init__.py,sha256=AMl15RijaEBf5frBP05HQnjHtwIvq7OOoANb-lH8DuA,525
19
+ tunarag/integrations/__init__.py,sha256=7eE5ScMAhleHTFwqglB5ZXR4oyjblovIIosIYYcO7CY,550
20
+ tunarag/integrations/google_adk.py,sha256=P_fL0g60Ok7dirwQlGxBq6BBMxNrP8OSEroSk9ciB8Q,5942
20
21
  tunarag/integrations/mlflow.py,sha256=Ig96h8CItgEnm-OX41Sp_MQvW9cbQureneZR2xCdikM,5807
21
- tunarag/integrations/runnables.py,sha256=xlHOjChMCBwXF-6Stu1jZT53NLgjAAJKMrWpW4K89GM,10034
22
- tunarag_python-0.2.1.dist-info/METADATA,sha256=VwYCBhocPINx1yCQTr6DsEfZ-yTJDrcYVDO7sYbAzao,37320
23
- tunarag_python-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
24
- tunarag_python-0.2.1.dist-info/RECORD,,
22
+ tunarag/integrations/runnables.py,sha256=B9RLnrpn8nZnYnOqkbDQmMmul2SfxOG8oOE-fiPv948,10268
23
+ tunarag_python-0.3.0.dist-info/METADATA,sha256=RwyQBcK6PfD1wMlpO-OQNYs2jxVQiQSl7cu3EdQvz8E,44254
24
+ tunarag_python-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
25
+ tunarag_python-0.3.0.dist-info/RECORD,,