MatchDay v3

Video demo: Watch MatchDay v3 on YouTube (1–3 minutes)

License: GNU Affero General Public License v3.0

Submission tracks

Track 1 — MemoryAgent (primary): persistent, owner-scoped travel memory that learns from verified trips, recalls critical preferences within a bounded context, and forgets stale or rejected evidence.
Track 4 — Autopilot Agent: an end-to-end travel-planning workflow that resolves ambiguous requests, invokes external tools, pauses at human approval gates, repairs conflicts, resumes after failure, and verifies every final plan.

Project description

Core promise: MatchDay remembers me, catches a trip-breaking conflict, and repairs my plan automatically.

MatchDay is a Qwen Cloud MemoryAgent and production-oriented Autopilot for high-stakes sports travel. It retains user-confirmed preferences across sessions, applies them to a new trip, invokes typed external tools, detects conflicts with deterministic rules, pauses for human approval at unsupported or high-risk boundaries, resumes durably after failure, asks Qwen to choose a repair, and independently verifies the repaired result before presenting it.

When the fan has not chosen a match yet, Qwen can search the complete official fixture cache by team, host city, country, date, or stage. A bounded match-list request returns up to 16 candidates. A host-city comparison returns one deterministic official representative for every eligible city, up to all 16, and cannot be truncated. MatchDay defaults to future fixtures when no date range is supplied, persists the city manifest and candidates before the next model call, and rejects any later intent that does not exactly match one of them.

Ten-second proof

The default scenario makes the product value visible in one sequence:

Remembered: the fan requires at least 420 minutes between airport arrival and kickoff.
Conflict detected: the lowest-cost flight leaves only 70 usable minutes after the stadium transfer.
Plan repaired: Qwen selects the lowest-cost safe alternative, flight MD087.
Result verified: an implementation-independent contract confirms the 455-minute buffer, budget, fixture certainty, match-day context evidence, full provenance, host city, and ranked-package requirements.

With SERPAPI_API_KEY configured, MatchDay searches Google Flights plus either Google Hotels or an explicit Google Vacation Rentals mode through SerpApi and normalizes at most three components per category. Vacation-rental requests set vacation_rentals=true, admit only records the provider types as rentals, expose only bounded occupancy/room facts, and do not inherit hotel-class, hotel-accessibility, or hotel-only memory semantics. For the final city, MatchDay privately resolves at most nine unique flight/return/stay seller tokens before building and ranking the 27 joint combinations; current seller prices replace search-level prices only after component identity, dates, party, property type, and safe checkout URL are rebound. Unknown or unavailable seller refund terms remain explicitly partial. The owner-only resolver can refresh a retained reference, but never exposes the provider token. With OPENROUTESERVICE_API_KEY configured, driving time/distance is sourced through the bounded Matrix adapter; otherwise OSRM is the route fallback. Neither route source is treated as a fare, refund term, inventory, availability, or booking proof. The SerpApi credential also enables two bounded Google Maps place searches per stadium/activity cache miss; MatchDay locally caches them for one hour, validates identity/category/coordinates/radius, and exposes only reported hours and safe public sites—not ticket inventory, luggage acceptance, or fees. Without provider credentials, the reproducible travel catalog preserves the requested hotel/rental category but remains explicitly labelled fixture data, while nearby evidence stays OpenStreetMap-only; neither path claims live commercial availability or booking.

With paired AMADEUS_API_KEY and AMADEUS_API_SECRET credentials, the final-city optimizer also requests four private-transfer legs—arrival airport to stay, stay to stadium, stadium to stay, and stay to departure airport—before package selection. Only non-estimated CAD quotes bound to the exact route, pickup time, party, capacity, provider, and full structured cancellation window enter exact-cent totals. Missing, partial, stale, mismatched, warning-qualified, or test-only evidence is labelled and excluded; Amadeus test responses are sandbox, production responses are live, and MatchDay transfer booking remains disabled. Flight/stay/transport refund coverage is separately reported as unavailable, partial, or complete instead of being inferred from a route or generic cancellation flag.

The same optional SerpApi credential also enables a separate, bounded general web_search tool; web_fetch can read only an exact public URL supplied by the user or returned by that search. Both tools enforce HTTPS, DNS/peer SSRF checks, redirect and domain policy, robots directives, credential rejection, time/size/result budgets, checkpoint caching with 15-minute freshness, and untrusted-content fencing. Search metadata and page text are always shown as Discovery evidence — not booking proof with citations. They cannot verify commercial prices, inventory, availability, refunds, luggage acceptance, opening hours, transfer fares, or booking status. MATCHDAY_WEB_BLOCKED_DOMAINS adds an operator-controlled comma-separated domain/subdomain deny policy.

In parallel, the Alibaba backend enriches the exact trip window with keyless Open-Meteo weather and bounded OpenStreetMap nearby-place evidence. When SerpApi is configured, validated Google Maps place metadata is merged source-first with OpenStreetMap and either source can fail independently. A configured UNSPLASH_ACCESS_KEY adds server-side destination photography with required hotlink metadata and photographer attribution. Each capability has an independent live, cached, fallback, or unavailable state; an outage never invents a forecast, place distance, commercial term, or image. Provider responses are timeout- and size-bounded before parsing, and the source-blind verification contract rejects missing or inconsistent context evidence.

Why memory matters

The safety rule is not copied into the request. It is recalled from a durable, user-owned memory record with source, confidence, timestamp, supersession, expiry, audit metadata, and a deduplicated reuse ledger. Retrieval combines exact travel facts with domain-semantic preference aliases under character and result-count limits. Memory proposals resolve to explicit ADD, UPDATE, DELETE, or NONE decisions, so repeated facts do not churn versions and explicit forget requests are auditable. One-trip facts are bound to the grounded host city and match date, so they cannot affect another fixture for the same fan. A safety limit stated for the current trip overrides durable profile memory without rewriting it. After verification, a fan can explicitly teach MatchDay which package style they chose; that choice changes a neutral later session while a new explicit request still wins. A completed trip can also become owner-checked context for a later refinement.

Refinements are real versions, not fresh lookalike plans. The fan can ask for the cheapest, safest-arrival, closest-to-stadium, or balanced package; deterministic scoring changes the winner, preserves parent/revision lineage, and applies walking or hotel-distance memories before verification.

Users can inspect, correct, delete, or disable memory. Deleted demo memories stay deleted. Every private read and write is owner-scoped. A verified run can create an immutable public page whose allowlisted snapshot removes memories, model metadata, tool history, user identity, source excerpts, and memory identifiers.

Architecture

Browser experience: the Next.js trip command center renders multi-turn chat, owner-only fan memory and provenance, durable trip versions, the decision trace, ranked packages, itinerary and evidence details, Explore Map, the 3D Stadium/Arrival Runway, the Stay Arrival dossier, and safe travel actions. Explore Map uses only sourced coordinates; Arrival Runway and Stay Arrival anchor their visual sequences to selected itinerary facts and label planning allowances, while the 3D bowl remains explicitly illustrative. Every immersive surface has a factual text/degraded fallback and never claims live traffic, seats, room imagery, inventory, accessibility, or booking.
Vercel private boundary: a signed HTTP-only guest session identifies the private workspace. The same-origin server facade binds the HTTP method, normalized path, exact raw query, body digest, timestamp, nonce, and guest identity; it propagates a separate validated request ID for correlation, rejects the operator namespace, and streams at most 1 MB (1,000,000 bytes) before allocation. The cookie-free public page is server-rendered from a separate allowlisted snapshot whose private memory, model, tool, identity, and execution fields have already been removed by Alibaba.
Alibaba ingress and control plane: Caddy terminates TLS, applies security headers and the same 1 MB ingress ceiling, and exposes only /healthz, /v1/*, and a static root status. FastAPI owns authorization, schemas, memory/run/thread/refinement/share APIs, seller-action resolution, typed events, and the separation between minimal public readiness and signed operator diagnostics.
Durable execution plane: a database-leased worker runs the Autopilot with fencing tokens, heartbeats, checkpoints, cancellation, retry classification, recovery, and cumulative attempt/model/tool/cost/time budgets. Request background dispatch and the polling worker contend through the same execution record, so only the current lease can spend work or persist progress.
Persistent MemoryAgent: explicit add/correct/delete/disable actions and autonomous Qwen proposals converge on one owner-scoped source of truth. Deterministic source/value grounding resolves proposals to ADD, UPDATE, DELETE, or NONE; fan and fixture-bound trip scopes, current-message precedence, bounded recall, expiry, supersession, audit history, and a deduplicated reuse ledger govern what can influence a later turn or session.
Autopilot decision loop: Qwen interprets intent and ambiguity, selects typed tools, proposes memory changes and repair choices, and explains the outcome. Deterministic code binds official fixture candidates, validates tool output, applies every active constraint, forms and ranks joint packages, detects conflicts, applies the selected repair, and independently revalidates the final version before it can be called verified.
Official fixture pipeline: a dedicated Alibaba worker refreshes all 104 matches from FIFA's first-party calendar feed every six hours, validates complete 16-host-city coverage before one atomic upsert, and serves the last verified PostgreSQL cache during outages. Qwen uses separate bounded-list and all-eligible-host-city modes; the latter selects exactly one official representative per eligible city and binds the complete city manifest plus selected candidate to the final intent.
Match-day context pipeline: Open-Meteo, OpenStreetMap/Overpass, optional bounded Google Maps enrichment through SerpApi, and optional Unsplash requests run server-side, fail independently, and persist typed provenance beside each itinerary version.
Joint package optimizer: SerpApi flight, return, and explicitly typed hotel or vacation-rental components are seller-resolved before they form at most 27 plausible combinations; optional Amadeus four-leg transfer fares/refund windows enrich every bounded candidate before selection; impossible timing is removed, near-duplicates collapse, and three truthful representatives drawn from cheapest, safest, closest, and balanced objectives survive final ranking.
Capability and handoff gates: the typed registry enforces credentials, provider tier/environment, timeouts, response/result bounds, approval policy, and an evidence ceiling. An owner-only travel-action gate rebinds component identity, route, airport-local date, party, property type, seller, freshness, and safe URL immediately before opening an exact offer; if that proof is absent, stale, redirected, contradictory, or a zero-result page, MatchDay fails closed to a typed dated search instead of presenting a broken commercial claim.
Storage: SQLite for local development; private PostgreSQL on the approved Alibaba ECS host in production.

See docs/ARCHITECTURE.md for the data flow and trust boundaries.

Run locally

Prerequisites: Node.js 22, Python 3.11+, and a Qwen Cloud API key for live-model runs.

npm ci
python3 -m pip install -e '.[dev]'
cp .env.example .env

Set DASHSCOPE_API_KEY in .env, then run the services in separate terminals:

PYTHONPATH=backend python3 -m uvicorn matchday.main:app --host 127.0.0.1 --port 8080
npm run dev -- --hostname 127.0.0.1 --port 3000

Open http://127.0.0.1:3000.

For deterministic local QA without consuming Qwen tokens:

MATCHDAY_QWEN_MODE=scripted PYTHONPATH=backend \
  python3 -m uvicorn matchday.main:app --host 127.0.0.1 --port 8080

The scripted adapter is a labelled test double for explicit development and test workflows. Startup fails closed when MATCHDAY_ENV=production is combined with MATCHDAY_QWEN_MODE=scripted. The real Qwen adapter is in backend/matchday/qwen.py; the bounded tool loop is in backend/matchday/agent.py.

Verification

npm test
PYTHONPATH=backend python3 -m matchday.evals
python3 -m playwright install chromium firefox webkit  # first cross-browser run only
npm run test:e2e
MATCHDAY_E2E_BROWSER=firefox MATCHDAY_E2E_API_PORT=8281 \
  MATCHDAY_E2E_WEB_PORT=3201 npm run test:e2e
MATCHDAY_E2E_BROWSER=webkit MATCHDAY_E2E_API_PORT=8381 \
  MATCHDAY_E2E_WEB_PORT=3301 npm run test:e2e
npm run test:postgres-concurrency  # isolated local Docker/PostgreSQL proof
npm run build
npm audit

The local E2E runner uses isolated localhost ports and a temporary SQLite database. Chromium is the default; the same source-blind journeys run in Firefox and WebKit with the environment settings above. It never calls paid remote test infrastructure.

Current covered gates include:

cross-session memory, one-pass exact/domain-semantic bounded model retrieval with idempotent checkpoint replay, fixture-scoped trip memory, explicit ADD/UPDATE/DELETE/NONE decisions, current-trip precedence, reuse/evidence/conflict usefulness scoring, visible fail-open recovery, forgetting, supersession, correction, deletion, and disablement;
owner-checked, objective-sensitive active-trip refinement with current-message precedence and explicit revision lineage;
cross-user isolation, signed-cookie tamper defense, exact query/body integrity, nonce replay defense, and incognito-tested public shares;
all 104 World Cup matches across all 16 host cities, first-party FIFA refresh, scheduled/on-demand cache updates, outage cooldown, official-cache/unconfirmed/stale states, and complete provider/source/confidence/limitation evidence;
flexible official fixture discovery with future-only defaults, bounded filters/results, non-truncating all-eligible-city comparison, durable city-manifest/candidate checkpoints, exact candidate-to-intent binding, no-match clarification, and browser-proven comparison flows;
bounded joint flight/return/stay generation with semantic dedupe, objective diversity, provider-backed stay quality and exact cancellation evidence when available, a type-bound vacation-rental path that excludes hotel-only semantics, an explicit unpriced local-transport state until sourced, and visible cost/arrival/proximity/stay/refund/memory/fixture/provenance/risk factors;
fail-closed accessibility enforcement: durable accessibility memory is always private, exact current-trip needs override memory, SerpApi filters on the official wheelchair-accessible amenity when relevant, only live provider evidence can satisfy a hotel-scoped wheelchair requirement, broader needs stop at a visible human checkpoint, and grounded removal can safely continue the same run;
current-trip-only entry constraints: explicit Canada/Mexico/USA allow/block scope is polarity-grounded and enforced against the selected host, while passport/visa review text rejects document identifiers, never becomes durable memory, and stops at a preserved human checkpoint because MatchDay does not claim legal eligibility;
exact-window weather, merged Google Maps/OpenStreetMap nearby-place evidence, and attributed destination-photo context with independent fail-open states, bounded response parsing, visible exact-record links, and a source-blind context verification gate;
provider fallback, Qwen failure/resume, durable per-tool checkpoints, stale-worker recovery, stale-proof invalidation, unknown-tool rejection, loop-stall handoff, and human approval;
source-blind rejection of unsafe or partially unresolved itineraries, plus final revalidation against current active memory;
complete Chromium, Firefox, and WebKit journeys, plus desktop/mobile layout behavior, public-share privacy/overflow, full proof-state order, and memory lifecycle after reload;
transient polling recovery, stale-run isolation, approval without a completed itinerary, readable validation failures with preserved drafts, destination-timezone invariance, keyboard package tabs, map/detail dialogs, share reset, and disabled-memory reload;
post-trip package-choice learning that changes a neutral next session but yields to a current explicit objective;
same-run clarification continuation, atomic resume/continue claims, provider-request binding, component-total recomputation, coherent contiguous ranks, dynamic fixture freshness, credential-shape rejection, full replay lifetime, and rate-limited resumes;
database-enforced memory, share, and worker invariants plus a barrier-synchronized PostgreSQL harness; the current release passed all eight isolated real-PostgreSQL concurrency/recovery cases;
atomic hourly run budgets (6 per user, 30 globally by default), a 12-step per-attempt Qwen loop, durable total attempt/model/tool/cost ceilings that retries cannot reset, and a wall-clock deadline on every attempt; the attempt ceiling keeps cumulative retry time bounded.

The versioned eval gate currently reports 100% required structured recall, 47.37% budget-limited naive-transcript recall, 0% no-memory recall, 52.63 points of structured lift, 0% cross-user leakage, 100% lifecycle checks, 100% objective ranking, 100% multi-factor coverage, 100% accessibility enforcement, 100% entry-constraint enforcement, 100% memory-sensitive ranking, and 100% official fixture discovery. Its 20-memory cross-city stress case retrieves the five required package-changing facts in seven results and 1,500 characters or less; local in-memory retrieval p95 must remain under 250 ms.

The exact-revision release gate completed with backend 1438 passed, PostgreSQL 8/8, Chromium 73 passed, Firefox 72 passed plus one expected Chromium-only WebGL skip, WebKit 72 passed plus the same expected skip, and zero browser failures.

Alibaba deployment

The production topology follows the V3 plan: the public Next.js UI and signed API facade run on Vercel, while Caddy, FastAPI, the durable database-leased agent worker, the fixture refresh worker, and private PostgreSQL run on one approved Alibaba ECS host. Caddy exposes only a static root status, /healthz, and /v1/* over automatic HTTPS; FastAPI enforces signed private/operator routes while keeping the allowlisted public-share read separate.

Optional Viator, openrouteservice, and paired Amadeus credentials are server-only. At Basic tier, Viator destinations, tags, attraction search/details, product search/details, and single-product schedules provide typed tours, luggage-storage, and destination-transfer catalog evidence; protected free-form attraction content is not rendered and generated app pages remain noindex. Viator catalogs never masquerade as exact four-leg transfer fares, real-time availability, or booking, and higher-tier capabilities stay disabled unless the declared account tier and implementation both qualify. ORS contributes route distance and duration as travel-friction evidence only—it never supplies fares or refund terms. Amadeus Transfer Search supplies commercial transfer evidence only in its configured test/production environment, and its booking path is also disabled. Anonymous /healthz returns only {"status":"ok"}. Sanitized capability/evidence tiers, aggregate runtime state, and the verified schema-contract version/fingerprint are available only from the direct, signed operator endpoint /v1/ops/health.

MatchDay also audits whether a credential is actually reachable, not merely present. Run PYTHONPATH=backend python3 -m matchday.integration_registry --env-file .env; it reports only provider names/states and exits non-zero for configured-but-inactive dependencies. The signed operator health snapshot publishes the sanitized matrix, and production verification fails if a credential or enabled feature is silently orphaned. See the integration registry implementation.

Startup can create absent tables, including the additive execution and share-claim companions, but it never rewrites an incompatible existing table. Readiness instead compares every required table, column type/nullability, primary key, index definition and partial predicate, unique constraint, and foreign key against the declared v3 contract. A mismatch fails startup or health with a generic external error, so an operator must preserve a backup and apply an explicitly reviewed migration rather than receiving a silent destructive schema change.

No script in this repository creates or resizes a cloud resource. Provisioning a billable Alibaba instance is a deliberate, manual approval gate. The existing-host workflow verifies the signed Vercel-to-Alibaba path and automatic-release deadline; the backup script streams PostgreSQL off-host before deployment, and a local destructive-only-to-temporary-containers drill proves restore. See deploy/alibaba/README.md.

Live app: https://matchday-v3-fawn.vercel.app

Public source repository: https://huggingface.co/mzidan000/matchday-v3

Alibaba Cloud deployment code: deploy/alibaba/docker-compose.yml defines the Caddy ingress, FastAPI backend, durable agent worker, fixture refresh worker, and PostgreSQL services running on the approved Alibaba ECS deployment.

Alibaba backend proof: ECS deployment verifier · production service stack · read-only ECS inventory · deployment runbook · health endpoint

Testing instructions for judges

No username, password, or API credentials are required.

Open https://matchday-v3-fawn.vercel.app in a fresh browser profile. MatchDay creates a new isolated guest profile with no silently seeded memories.
Select Use demo scenario, then select Plan this trip.
Watch the visible Remembered → Conflict detected → Plan repaired → Result verified workflow.
Expand the decision trace and its Memory → Plan → Tools → Repair → Verify proof map to inspect factual tools, sources, outcomes, freshness, and timing.
Inspect the persistent profile and memory provenance. Add or edit a preference, reload the page, and confirm that it remains available in the same browser.
Enter a one-word follow-up such as cheaper or closer and verify that MatchDay refines the existing trip instead of restarting it.
Inspect the new immutable trip version, ranked packages, independent verification contract, Explore Map, Stadium Lens perspective, and safe public share.
Open the application in another browser or private window to confirm that it receives a separate guest profile.
Review the evidence labels: provider results distinguish fixture, sandbox, discovery, cached, live, available, and bookable evidence. MatchDay does not perform purchases or invent missing prices, availability, refund terms, or booking claims.

Submission assets

License

MatchDay v3 is open source under the GNU Affero General Public License v3.0, identified by the SPDX expression AGPL-3.0-only.

Limitations

SerpApi and Amadeus availability, seller links, prices, and cancellation rules remain third-party observations and can change after capture. MatchDay resolves bounded exact seller evidence before final ranking, expires its verification after 15 minutes, asks the user to recheck before purchase, and does not complete bookings.
Google Vacation Rentals coverage comes from SerpApi's Google Hotels engine rather than direct Airbnb or Vrbo inventory. MatchDay requires the provider's rental type at search and resolution time, but still treats seller availability and commercial terms as unverified until an exact offer exposes them.
The checked-in FIFA-normalized seed keeps all 104 fixture slots available when the official endpoint is down. It is separate from the deterministic, fixture-labelled travel-offer catalog used to reproduce conflict and repair without provider credentials. The scheduled worker validates a complete official response before updating PostgreSQL; failed or partial responses preserve the last verified cache and surface a stale warning.
Weather is a forecast rather than a guarantee. Google Maps/SerpApi and OpenStreetMap place metadata can be cached and does not confirm trip-date opening status, tickets, luggage acceptance, inventory, charges, or match-day access; destination photography is illustrative. MatchDay surfaces those limitations and keeps an explicit unavailable/fallback state when a source cannot answer.
The public proof deployment uses one approved Alibaba host; console and live-app evidence are recorded separately from source so credentials and operator details cannot leak into the repository.

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support