agentic-google-flights-tool 0.1.0__tar.gz

agentic_google_flights_tool-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agentic-google-flights-tool/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agentic_google_flights_tool-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+**/__pycache__/
+artifacts/
+.coverage
+.DS_Store
+build/
+dist/
+*.egg-info/

agentic_google_flights_tool-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+This project uses semantic versioning once releases begin.
+
+## 0.1.0
+
+- Added bounded batch search through browser automation.
+- Added round-trip and multi-city ticket verification.
+- Added caching, local filtering, ranking, and progressive result views.
+- Added structured coverage and error reporting.

agentic_google_flights_tool-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+This is a small, best-effort project. Focused bug reports and pull requests are welcome, but response times may vary.
+
+Before starting a large change, open an issue to check whether it fits the project. For a code change:
+
+1. Use Python 3.11 or newer.
+2. Install the development environment with `uv sync --extra dev`.
+3. Add or update tests for changed behavior.
+4. Run `uv run pytest` and `uv run ruff check .`.
+5. Keep generated search results, browser caches, and personal travel data out of commits.
+
+Tests should be deterministic by default. Mark tests that contact Google with `pytest.mark.live` and run them only when the external request is the point of the test.
+
+By contributing, you agree that your contribution will be licensed under the MIT License.

agentic_google_flights_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Tamez Gonzalez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_google_flights_tool-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: agentic-google-flights-tool
+Version: 0.1.0
+Summary: Explore and compare flight options with AI agents
+Project-URL: Homepage, https://github.com/alberto-tamez/agentic-google-flights-tool
+Project-URL: Repository, https://github.com/alberto-tamez/agentic-google-flights-tool
+Project-URL: Issues, https://github.com/alberto-tamez/agentic-google-flights-tool/issues
+Author: Alberto Tamez Gonzalez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: browser-automation,flights,google-flights,travel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.11
+Requires-Dist: fast-flights==3.1.0
+Requires-Dist: playwright<2,>=1.62
+Requires-Dist: pydantic<3,>=2.10
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: fli
+Requires-Dist: flights==0.9.0; extra == 'fli'
+Description-Content-Type: text/markdown
+
+# Agentic Flights
+
+Find the best flights for your trip with your AI. Compare flexible dates, nearby airports, and trip lengths, then get a shortlist of the options worth booking.
+
+## Give this to your AI
+
+Copy this into an AI agent with terminal access and add your trip details:
+
+```text
+Install and use Agentic Flights from
+https://github.com/alberto-tamez/agentic-google-flights-tool.
+Follow its README and the bundled agent guide to find the best flights for my trip.
+
+My trip: [departure city, destination, dates or flexibility, travelers,
+and preferences].
+```
+
+For example: “Madrid or Barcelona to Japan for about two weeks in October 2027. One adult, an overhead cabin bag, and at most one stop. I'd like a good balance of price and travel time.”
+
+## Install
+
+Requires Python 3.11 or newer. Install the Python package from GitHub:
+
+```sh
+python -m pip install "git+https://github.com/alberto-tamez/agentic-google-flights-tool.git"
+```
+
+Then read the included instructions:
+
+```sh
+agentic-flights guide
+```
+
+The tool uses Google Chrome if installed. Otherwise:
+
+```sh
+python -m playwright install chromium
+```
+
+## For agents
+
+Start with `agentic-flights guide`. Load `agentic-flights guide reference` or
+`agentic-flights guide schema` only when needed. Explore and compare results in
+code, keep full reports outside the conversation, and verify the strongest
+options before recommending them.
+
+The package includes a Python API and CLI. An MCP server is not included yet.
+Search coverage is limited by what Google returns, and fares can change.
+This unofficial project is not affiliated with Google.
+
+[Agent guide](docs/agent-guide.md) · [Technical reference](docs/reference.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

agentic_google_flights_tool-0.1.0/README.md

@@ -0,0 +1,51 @@
+# Agentic Flights
+
+Find the best flights for your trip with your AI. Compare flexible dates, nearby airports, and trip lengths, then get a shortlist of the options worth booking.
+
+## Give this to your AI
+
+Copy this into an AI agent with terminal access and add your trip details:
+
+```text
+Install and use Agentic Flights from
+https://github.com/alberto-tamez/agentic-google-flights-tool.
+Follow its README and the bundled agent guide to find the best flights for my trip.
+
+My trip: [departure city, destination, dates or flexibility, travelers,
+and preferences].
+```
+
+For example: “Madrid or Barcelona to Japan for about two weeks in October 2027. One adult, an overhead cabin bag, and at most one stop. I'd like a good balance of price and travel time.”
+
+## Install
+
+Requires Python 3.11 or newer. Install the Python package from GitHub:
+
+```sh
+python -m pip install "git+https://github.com/alberto-tamez/agentic-google-flights-tool.git"
+```
+
+Then read the included instructions:
+
+```sh
+agentic-flights guide
+```
+
+The tool uses Google Chrome if installed. Otherwise:
+
+```sh
+python -m playwright install chromium
+```
+
+## For agents
+
+Start with `agentic-flights guide`. Load `agentic-flights guide reference` or
+`agentic-flights guide schema` only when needed. Explore and compare results in
+code, keep full reports outside the conversation, and verify the strongest
+options before recommending them.
+
+The package includes a Python API and CLI. An MCP server is not included yet.
+Search coverage is limited by what Google returns, and fares can change.
+This unofficial project is not affiliated with Google.
+
+[Agent guide](docs/agent-guide.md) · [Technical reference](docs/reference.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

agentic_google_flights_tool-0.1.0/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+## Supported versions
+
+Only the latest version on the default branch receives security fixes. This project is maintained on a best-effort basis and does not promise a response or release schedule.
+
+## Reporting a vulnerability
+
+Do not include credentials, private booking links, personal travel details, or a working exploit in a public issue.
+
+Use GitHub's private vulnerability reporting for this repository if it is available. If it is not available, open a public issue that contains only a short request for a private contact channel. Include enough information to distinguish a security report from a normal bug, but omit sensitive details.
+
+Reports about changes to Google Flights markup or undocumented responses are ordinary compatibility bugs unless they expose private data or create a security boundary failure.

agentic_google_flights_tool-0.1.0/docs/agent-guide.md

@@ -0,0 +1,44 @@
+# Agentic Flights: agent guide
+
+Use this tool to answer a trip-planning question with a small, useful shortlist. Run searches and comparisons in code; return only the evidence the user needs to choose.
+
+## Setup and instructions
+
+After installing the package, run `agentic-flights guide` from any directory.
+Use an installed Google Chrome, or run `python -m playwright install chromium`.
+Read `agentic-flights guide reference` for Python examples and detailed fields;
+read `agentic-flights guide schema` for the JSON input schema. These instructions
+are bundled with the installed version; no repository checkout is required.
+
+## Turn the goal into a search
+
+Identify origin and destination airport choices, departure dates, trip lengths, passengers, currency, and hard requirements. Resolve relative dates to concrete dates and cities to explicit airport codes. Clarify only missing information that changes the search.
+
+For flexible one-way or round-trip searches, use `SearchSpace` and check `space.count` before executing. Choose reasonable internal batch sizes and continue exploring relevant alternatives. Respect any explicit user budget, but do not require users to specify a combination count. If the search is too broad to complete, narrow it using the trip preferences and explain the remaining uncertainty. For exact or multi-city itineraries, supply `SearchSpec` requests to `BatchExecutor` or the CLI.
+
+The [Python example](reference.md#programmatic-trip-exploration) shows the API setup. Read it when implementing the search; consult the rest of the reference only for fields you need.
+
+## Explore, compare, verify
+
+1. Start with `search_mode="discover"` and apply the user's price, stop, and timing constraints. Keep browser concurrency at two workers.
+2. Execute bounded batches. With `Exploration.advance`, save the returned `run_id` and pass it as `resume_from` to continue the same space. Continue through the relevant search space, respecting any explicit user budget. Failures count as attempted; inspect them before claiming coverage.
+3. Filter and rank saved results in code. Compare prices within the same currency and preserve useful price-versus-duration choices. Keep full result JSON outside model context.
+4. Run `search_mode="verify"` for the shortlisted trip queries that need complete prices or baggage evidence. Verification searches current inventory again; it does not lock a discovery result. Never present provisional multi-leg prices or summed one-way fares as a verified complete ticket.
+
+## Read only what you need
+
+Run these commands from any directory, replacing the IDs with returned values:
+
+```sh
+agentic-flights summary RUN_ID
+agentic-flights list RUN_ID --page-size 5
+agentic-flights show RUN_ID RESULT_ID
+```
+
+Use `list --filters` to narrow results offline. Expand only finalists with `show`; it includes fare evidence and booking URLs. Avoid `--full` in conversational tool output. Saved runs can expire; export results the user needs to keep.
+
+## Return a decision
+
+Present a short comparison with total price and currency, dates, airports, duration, stops, and verified baggage where relevant. Explain why each option is worth considering. Include booking links when available and distinguish verified totals from provisional prices.
+
+State how many combinations were attempted, failures, remaining queries, and any retrieval limits that affect the recommendation. Exhausting the defined search space does not prove the global lowest fare. Do not book tickets.

agentic_google_flights_tool-0.1.0/docs/reference.md

@@ -0,0 +1,152 @@
+# Technical reference
+
+Read this when you need field definitions, retrieval limits, storage behavior, or Python examples. For the main workflow, start with the [agent guide](agent-guide.md). CLI commands work after package installation. Commands using repository examples or scripts require a checkout. The Python API keeps its compatible `reverse_google_flights` import name.
+
+## Install
+
+```sh
+uv sync --extra dev
+```
+
+The browser provider uses an installed Google Chrome when available. Otherwise, install Playwright Chromium with `uv run playwright install chromium`.
+
+The optional `fli` comparison provider uses its latest published release:
+
+```sh
+uv sync --extra dev --extra fli
+```
+
+## Run a batch
+
+Start with one search:
+
+```sh
+agentic-flights examples/search-one.json
+```
+
+Then run the 50-search example if you want to exercise batching:
+
+```sh
+agentic-flights examples/searches-50.json
+```
+
+The command stores the full report in the managed cache. Standard output contains an `rgf_...` run ID, counts, coverage, five short previews, and commands for reading the saved results. Use `--output PATH` to keep a separate export; the automatic cleanup never removes explicit exports. Use `--full` to write the complete report to standard output.
+
+Input may also come from standard input. Set `provider` to `browser` or `fli`. Keep `max_workers` at 2 for browser searches. The `ranked_by_currency` field never compares prices across currencies.
+
+Use `search_mode: discover` to retrieve many candidates with less browser work. The browser reads Google's Best tab and clicks the visible `View more flights` control up to `load_more_clicks` times. `retrieval_limit` defaults to 250 and caps the candidates read from the page. It does not control `max_results`, complete-quote budgets, or shortlist size. Coverage records loaded candidates, DOM duplicates, parser losses, clicks, and why retrieval stopped. Google's Best tab may omit other available flights.
+
+Set `max_stops`, `max_price`, and `segment_filters` to filter the Google query before retrieval. Segment filters accept `airlines`, departure and arrival hour bounds, and `max_duration_minutes`. Put return-flight filters in `return_segment_filters`; each additional multi-city segment has its own `filters`. Hours are airport-local integers from 0 through 23, and a window cannot cross midnight. Airlines use two-character IATA codes or the identifiers `ONEWORLD`, `SKYTEAM`, and `STAR_ALLIANCE`.
+
+Multi-leg discovery returns first-stage `outbound_choice` records with `ticket_scope: partial_or_unknown`. Their prices are provisional; adding one-way prices or presenting them as complete tickets would be incorrect.
+
+Filter and rank a saved report without another Google request:
+
+```sh
+agentic-flights list RUN_ID --filters - --page-size 5 <<'JSON'
+{"max_price": 150, "max_total_stops": 0, "limit": 5}
+JSON
+```
+
+Local filters support request IDs, price, total duration, total stops, airline names or codes, departure hours, overhead cabin baggage, and complete-ticket scope. Missing evidence fails a hard filter and appears in `unknown_by`. The shortlist report preserves source coverage, parse losses, and truncation separately.
+
+Inspect a saved report without printing the full JSON:
+
+```sh
+agentic-flights summary RUN_ID
+agentic-flights list RUN_ID --page-size 5
+agentic-flights show RUN_ID RESULT_ID
+```
+
+`list` filters before pagination and returns at most 20 slim records. Its cursor binds the dataset contents, filter, sort order, and offset. `show` accepts at most ten stable result IDs and is the only default view that returns full fare evidence and booking URLs. Use `summary SOURCE --full` for an explicit full export.
+
+Managed runs live in the platform's user cache directory, and reading a run refreshes its idle timestamp. Cleanup keeps at most 50 runs, removes runs idle for 7 days, and limits managed reports plus the provider cache to 100 MB. Cleanup touches only regular files inside the store marked as owned by this application. System temporary folders, project artifacts, explicit exports, and explicit `--cache-dir` paths are outside its scope.
+
+Each browser result includes numeric price, duration, stop count, airline name, local departure time, and local arrival time. A one-way result normally has `ticket_scope: partial_or_unknown` because the search page does not prove the final ticket terms. A hard cabin-bag requirement uses the same bounded final-page exploration as complete trips.
+
+For a round trip, the browser provider explores a bounded tree of outbound and return choices. It replays every selected path in a fresh page and accepts a result only after Google shows a final booking page. Each option contains both journeys, the exact combined price from the itinerary summary, `price_provenance: provider_final_total`, and `ticket_scope: complete_single_ticket`. The provider does not add independent one-way fares or continue to a seller.
+
+For an open-jaw or another multi-city ticket, keep the first journey in `origin`, `destination`, and `departure_date`. Add later journeys to `additional_segments` in travel order. The same bounded traversal verifies each returned path on its own final page. The input schema rejects requests that combine `additional_segments` with `return_date`.
+
+Use `candidates_per_stage` to control the Google-ordered choices explored at each journey. Use `max_complete_quotes` and `max_browser_transitions` as total work budgets. `max_results` only limits returned options. Defaults are 2 candidates per stage, 4 completed quote attempts, and 24 browser transitions. Complete-ticket options sort by final price, total duration, stop count, and itinerary identity.
+
+Every outcome has `coverage`. It reports candidates seen, terminal branches attempted, quotes completed and filtered, duplicates, pruned branches, branch errors by code, browser transitions, and budget exhaustion. `fully_explored` is true only when no candidate, output, error, or budget truncated the observed tree. A successful bounded result is not a guarantee of Google's global lowest fare. Cached outcomes retain the original discovery coverage while `requests_made` is zero for the cache replay.
+
+For agent-driven multi-leg work, discover route and date queries first, apply upstream constraints, and shortlist the saved provisional results. Run `search_mode: verify` only for the two or three shortlisted trip queries that need a final seller quote and baggage evidence. Verification reruns current Google results; a provisional rank does not lock the same flight after inventory or prices change.
+
+Set `overhead_cabin_bags` to the requested number of overhead cabin bags. With `require_overhead_cabin_bag: true`, the selected fare passes only when its seller option or selected-flight summary states that carry-on baggage is included for the entire trip. Missing evidence, extra-cost baggage, and personal-item-only allowances fail the filter with a structured error.
+
+## Programmatic trip exploration
+
+`SearchSpace` expands airport choices, an inclusive departure window, and optional
+stay lengths into exact searches. `space.count` previews the work without opening
+a browser. Airport lists are normalized and deduplicated; same-airport routes are
+excluded. This first API supports one-way and round-trip spaces with at most
+100,000 combinations. Supply explicit airport codes; city resolution and adaptive
+search allocation are not implemented.
+
+```python
+from datetime import date, timedelta
+
+from reverse_google_flights import BatchExecutor, Exploration, SearchSpace, SearchSpec
+from reverse_google_flights.cache import FileCache
+from reverse_google_flights.provider import BrowserProvider
+from reverse_google_flights.store import ManagedStore
+
+departure = date.today() + timedelta(days=60)
+space = SearchSpace(
+    template=SearchSpec(
+        request_id="template", origin="MAD", destination="NRT",
+        departure_date=departure, currency="EUR", language="en", country="ES",
+        search_mode="discover",
+    ),
+    origins=["MAD", "BCN"], destinations=["NRT", "HND", "KIX"],
+    departure_start=departure, departure_end=departure + timedelta(days=6),
+    min_nights=12, max_nights=15,
+)
+assert space.count == 168
+store = ManagedStore()
+store.initialize()
+executor = BatchExecutor(
+    FileCache(store.provider_cache / "browser", namespace=BrowserProvider.version),
+    max_workers=2,
+)
+exploration = Exploration(space, executor, store)
+progress = exploration.advance(search_budget=20)
+print(progress.model_dump_json())  # Counts, run ID, and at most five previews.
+
+# A later process can reconstruct the same configuration and continue.
+progress = exploration.advance(resume_from=progress.run_id, search_budget=20)
+```
+
+Each call attempts at most `search_budget` combinations, including cache hits,
+with a maximum of 500. This is a query budget, not a browser-transition or elapsed
+time limit. Template settings still bound the work inside each query. Full results
+stay in the managed store; use the existing `list` and `show` commands with the
+returned run ID to inspect them without another Google request.
+
+Each completed batch produces an immutable snapshot containing all outcomes so
+far. Save the latest run ID to resume. Reusing an older ID branches from that
+snapshot; it does not advance a shared job. An interruption before a batch returns
+can require replaying that batch, with available successful cache entries reused.
+Managed-store expiration still applies, and snapshots retain their original fare
+observations. Changed search-space or provider-namespace settings reject resume.
+
+Failures count as attempted and remain in the report. `search_space_exhausted`
+means every defined query was attempted, even if some failed; it does not mean
+every available fare was retrieved. Retry failed queries or verify shortlisted
+queries separately through `BatchExecutor`. MCP transport and automatic finalist
+selection are not part of this API yet.
+
+## Limits
+
+Google Flights does not publish a consumer search API. Both providers depend on undocumented behavior that Google can change. Each browser result records `observed_at`; it is a dated observation and does not guarantee the fare. Confirm the price, baggage rules, and availability with the seller before purchase. The browser parser reads English result labels even when the request specifies another language tag.
+
+Use conservative batch sizes and concurrency. You are responsible for complying with the terms, policies, and laws that apply to your use. Do not use this project to evade access controls, overload services, or automate purchases.
+
+The input schema requires concrete travel dates, so the checked-in examples eventually expire. Update them with:
+
+```sh
+uv run python scripts/refresh_example_dates.py
+```
+

agentic_google_flights_tool-0.1.0/examples/branching-combinations-live.json

@@ -0,0 +1,52 @@
+{
+  "provider": "browser",
+  "max_workers": 1,
+  "cache_ttl_seconds": 3600,
+  "ranking_limit": 8,
+  "searches": [
+    {
+      "request_id": "round-trip-2x2",
+      "origin": "MAD",
+      "destination": "LIS",
+      "departure_date": "2027-01-21",
+      "return_date": "2027-01-28",
+      "cabin": "economy",
+      "max_stops": "non_stop",
+      "adults": 1,
+      "overhead_cabin_bags": 1,
+      "require_overhead_cabin_bag": true,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_results": 4,
+      "candidates_per_stage": 2,
+      "max_complete_quotes": 4,
+      "max_browser_transitions": 24
+    },
+    {
+      "request_id": "open-jaw-2x2",
+      "origin": "MAD",
+      "destination": "CDG",
+      "departure_date": "2026-11-18",
+      "additional_segments": [
+        {
+          "origin": "AMS",
+          "destination": "MAD",
+          "departure_date": "2026-11-25"
+        }
+      ],
+      "cabin": "economy",
+      "max_stops": "one_stop_or_fewer",
+      "adults": 1,
+      "overhead_cabin_bags": 1,
+      "require_overhead_cabin_bag": true,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_results": 4,
+      "candidates_per_stage": 2,
+      "max_complete_quotes": 4,
+      "max_browser_transitions": 24
+    }
+  ]
+}

agentic_google_flights_tool-0.1.0/examples/complete-tickets-live.json

@@ -0,0 +1,46 @@
+{
+  "provider": "browser",
+  "max_workers": 1,
+  "cache_ttl_seconds": 3600,
+  "ranking_limit": 5,
+  "searches": [
+    {
+      "request_id": "round-trip-with-cabin-bag",
+      "origin": "MAD",
+      "destination": "LIS",
+      "departure_date": "2027-01-21",
+      "return_date": "2027-01-28",
+      "cabin": "economy",
+      "max_stops": "non_stop",
+      "adults": 1,
+      "overhead_cabin_bags": 1,
+      "require_overhead_cabin_bag": true,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_results": 1
+    },
+    {
+      "request_id": "open-jaw-with-cabin-bag",
+      "origin": "MAD",
+      "destination": "CDG",
+      "departure_date": "2026-11-18",
+      "additional_segments": [
+        {
+          "origin": "AMS",
+          "destination": "MAD",
+          "departure_date": "2026-11-25"
+        }
+      ],
+      "cabin": "economy",
+      "max_stops": "one_stop_or_fewer",
+      "adults": 1,
+      "overhead_cabin_bags": 1,
+      "require_overhead_cabin_bag": true,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_results": 1
+    }
+  ]
+}

agentic_google_flights_tool-0.1.0/examples/open-jaw-branching-live.json

@@ -0,0 +1,33 @@
+{
+  "provider": "browser",
+  "max_workers": 1,
+  "cache_ttl_seconds": 3600,
+  "ranking_limit": 4,
+  "searches": [
+    {
+      "request_id": "open-jaw-two-quotes",
+      "origin": "MAD",
+      "destination": "CDG",
+      "departure_date": "2026-11-18",
+      "additional_segments": [
+        {
+          "origin": "AMS",
+          "destination": "MAD",
+          "departure_date": "2026-11-25"
+        }
+      ],
+      "cabin": "economy",
+      "max_stops": "one_stop_or_fewer",
+      "adults": 1,
+      "overhead_cabin_bags": 1,
+      "require_overhead_cabin_bag": true,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_results": 2,
+      "candidates_per_stage": 2,
+      "max_complete_quotes": 2,
+      "max_browser_transitions": 14
+    }
+  ]
+}

agentic_google_flights_tool-0.1.0/examples/retrieval-filtering-live.json

@@ -0,0 +1,63 @@
+{
+  "provider": "browser",
+  "max_workers": 1,
+  "cache_ttl_seconds": 3600,
+  "ranking_limit": 10,
+  "searches": [
+    {
+      "request_id": "mad-lhr-broad",
+      "origin": "MAD",
+      "destination": "LHR",
+      "departure_date": "2027-01-21",
+      "cabin": "economy",
+      "max_stops": "any",
+      "adults": 1,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "search_mode": "discover",
+      "retrieval_limit": 250,
+      "load_more_clicks": 1
+    },
+    {
+      "request_id": "mad-lhr-upstream-filtered",
+      "origin": "MAD",
+      "destination": "LHR",
+      "departure_date": "2027-01-21",
+      "cabin": "economy",
+      "max_stops": "non_stop",
+      "adults": 1,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_price": 200,
+      "segment_filters": {
+        "airlines": [
+          "IB"
+        ],
+        "earliest_departure_hour": 7,
+        "latest_departure_hour": 18,
+        "max_duration_minutes": 180
+      },
+      "search_mode": "discover",
+      "retrieval_limit": 250,
+      "load_more_clicks": 1
+    },
+    {
+      "request_id": "mad-lis-round-trip-discovery",
+      "origin": "MAD",
+      "destination": "LIS",
+      "departure_date": "2027-01-21",
+      "return_date": "2027-01-28",
+      "cabin": "economy",
+      "max_stops": "one_stop_or_fewer",
+      "adults": 1,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "search_mode": "discover",
+      "retrieval_limit": 100,
+      "load_more_clicks": 1
+    }
+  ]
+}

agentic_google_flights_tool-0.1.0/examples/round-trip-outbound-choice.json

@@ -0,0 +1,22 @@
+{
+  "provider": "browser",
+  "max_workers": 1,
+  "cache_ttl_seconds": 3600,
+  "ranking_limit": 5,
+  "searches": [
+    {
+      "request_id": "mad-lis-round-trip",
+      "origin": "MAD",
+      "destination": "LIS",
+      "departure_date": "2026-12-04",
+      "return_date": "2026-12-12",
+      "cabin": "economy",
+      "max_stops": "non_stop",
+      "adults": 1,
+      "currency": "EUR",
+      "language": "en-US",
+      "country": "ES",
+      "max_results": 5
+    }
+  ]
+}