Agent price pilot: offline contract reference

Status: offline reference with approved first-trial requirements, 2026-10-16. Open implementation and qualification work remains solely in BACKLOG.md, under AGPIPE-1 through AGPIPE-10. This document specifies the bounded example; it does not certify a provider, account, live watchlist or production release. The user selected TinyFish as the first qualification candidate; see the qualification record for the approved gates, selected trial candidates and remaining capability checks.

What this slice demonstrates

Three existing DataContract instances describe requested targets, captured price candidates and normalized observations. They parse, persist through Store, build validators from retained definitions, and validate synthetic records. No agent step, adapter, normalization implementation, managed dataset connector, evidence store or complete-publication gate ships here. There is deliberately no runnable agent Pipeline example yet.

The future workflow is: read stored watchlist → freeze targets → collect raw observations → transform deterministically → validate records and evaluate identity/evidence/freshness/coverage → release a complete managed dataset. Acquisition preserves displayed money and package text. Conversion belongs in transform, not in the browser instructions or executor settings.

Approved public-offer meaning

On 2026-10-16 the user selected public, logged-out Hong Kong single-item offers, including unconditional discounts. Exclude delivery fees, member pricing, coupons, multi-buy, exchange and checkout-dependent offers. A struck-through reference/list price or comparison amount is not an offered price. Preserve an observed discount as promotional; do not relabel it ordinary. Eligibility, exact seller, variant, package and regional context require evidence review.

The original version 0.1.0 examples retain their historical ordinary-only meaning. The additive version 0.2.0 examples implement the approved record boundary. They separate the target's requested offer policy from the category, role and conditions actually observed. They do not implement a browser task or prove that a real offer is unconditional. A page without an eligible public offer is unresolved unless correct-product evidence explicitly establishes unavailability.

The target identifies source product, merchant, variant and expected package in grams. Observations record the identity actually seen; the agent must not copy requested values into these fields without observing them. Product IDs and a reviewed mapping take precedence over fuzzy title matches. Displayed package text is retained in raw output before conversion to grams.

context_id: public_hk_zh_hant denotes a proposed public, unauthenticated Hong Kong context with Traditional Chinese presentation. It is a non-secret reference, not proof of network location or permission. Actual routing, language, account absence and any price-affecting context must be captured and checked in the run. Unexpected login or location changes block the target; they must not silently change its meaning.

An unavailable observation is valid only when evidence identifies the correct product and explicitly shows that it cannot be purchased. It has null price. Navigation failure, missing page, blocked access, uncertain identity and no qualifying public offer are unresolved operational outcomes, not unavailable rows. This example stores only observed and unavailable record candidates; blocked/ambiguous/failed attempts belong in the future run ledger.

Contracts and monetary representation

Historical version 0.1.0 files live in src/pycharter/data/seed/examples/agent_price_pilot/contracts/:

Existing artifact kind	Name at version 0.1.0	Boundary
DataContract	watchlist_target	Required target identity and price context
DataContract	raw_price_observation	Observed identity, displayed price/package, time and evidence references
DataContract	price_observation	Ordinary HKD price in integer cents, normalized package in grams

Version 0.2.0 lives separately in src/pycharter/data/seed/examples/agent_price_pilot/v0_2_0/contracts/. watchlist_target requires offer_policy: public_single_item_unconditional_v1; raw observations preserve observed price role/category/conditions, including unknown or excluded candidates. Accepted observed final records require an ordinary or promotional offer with empty eligibility conditions, positive integer HKD cents and independently supported public context. Accepted unavailable records require explicit null for every price/classification field, including currency. See the contract reference for opt-in migration and validation limits.

Both revisions use namespace agent_price_pilot, envelope pycharter.io/v2, strict types and closed record properties. Their versions are draft example identities, not approved business schemas. They are explicitly imported examples, like the FMP reference artifacts, with no automatic seed manifest or execution. No new artifact kind, global version, public API or dependency is introduced.

The proposed normalization rule hkd_minor_units_v1 preserves the raw price, accepts only reviewed HKD display syntax, parses decimal digits using exact decimal arithmetic, and multiplies by 100 without rounding. For example, HK$129.90 becomes integer 12990. Currency ambiguity, unsupported separators, more than two decimal places, negative amounts and zero fail the pilot rule. Do not parse with binary floats, infer a discount, or convert null to zero. Package normalization similarly converts the explicitly observed 2 kg to 2000 g using a pinned, reviewed conversion; unsupported units are unresolved. The tests establish the final integer representation and conditional null rules; they do not claim that a price/package parser already implements them.

The conditional schema enforces explicit null for unavailable candidates and a positive amount for observed final records. Missing fields, null, unknown and zero remain distinct. Other currencies or conditional prices can be raw candidates but cannot satisfy the final public-offer HKD contract at 0.2.0. Coercion is not used to make inconsistent money values pass. The existing declared coerce_to_datetime rule converts only observed_at; PyCharter represents date-time fields as Python datetimes even when the transport is JSON. Version 0.1.0 uses a root allOf timezone check; 0.2.0 applies the timezone pattern directly to observed_at after this conversion, preserving strict money types and rejecting naive or invalid timestamps.

Acceptance beyond record validation

The historical fixture file contains one synthetic 2 kg rice target and ordinary, unavailable, member, coupon, mislabeled-member, wrong-merchant, wrong-variant, wrong-package, missing-evidence and contradictory-price cases. URLs use example.com; no real products, accounts, prices or retained page captures are represented. Fixture case replacements are a test-data convenience, not a task format or new configuration language.

Version 0.2.0 adds 27 synthetic cases for unconditional discounts, price roles, conditions, unknown currency and unavailable null fields. Individual schemas cannot detect a discount relabeled ordinary, a reference relabeled an offer or conditions dropped during transformation. Those paired cases require AGPIPE-3 to compare retained raw/final records against independently supported facts.

The canonical validator rejects declared member/coupon prices and invalid money/null shapes. It accepts schema-valid wrong identities and syntactically valid nonexistent evidence references. A member price falsely labeled ordinary can also pass the record schema. Those cases require independent evidence and target checks in AGPIPE-3. An evaluator that cannot determine a required fact must return indeterminate; agreement between models is not ground truth.

Before submission, freeze the validated inputs and reject duplicate target keys. Empty inputs should produce an explicit no-work result with no provider submission and no snapshot publication. Every frozen target needs one current accepted outcome; duplicate, unexpected and missing target outcomes fail coverage. The initial publication policy requires 100% accepted target coverage, including correctly evidenced unavailable outcomes. Stage all rows until this gate passes. A completed provider job and valid individual rows cannot release an incomplete dataset.

Observation timestamps include a timezone. Proposed live freshness bounds are a maximum 30-minute observation spread and an oldest observation no more than 60 minutes old at publication. These are planning assumptions, not approved or enforced defaults. Resumption must re-observe stale targets or withhold output. The user approved 20 attempts, zero accepted factual errors, 100% publication coverage, mean cost at most US\(0.50 per accepted target and a US\)20 first-candidate budget. Freshness, duration, p95 and intervention numbers remain proposals. These are acceptance requirements; no measured result or enforcement is claimed.

Store authority and evidence

For the managed pilot, the outer application resolves one database, SQLite by default. Contracts and Pipeline definitions are imported through existing Store clients. Runs use exact retained identities/versions and digests; YAML is an authoring/export surface, not a second runtime registry. Existing contract CRUD alone does not guarantee definition immutability; PIPE-4C covers that boundary.

Targets, frozen requirements, attempts, raw and normalized observations, required evidence bytes/metadata and publication receipts must use that same database through public Store clients. No task-controlled state database, filesystem recovery sidecar or provider-only evidence authority is introduced. Operational evidence and lifecycle records are not new domain artifact kinds. The dataset/ledger/evidence clients remain AGPIPE-4 work; the lifecycle tests in this slice demonstrate only contract persistence and validation.

Minimum evidence should show the product identity, merchant, selected variant, package and price/conditions or explicit unavailable state, with source URL and capture time. The ledger must retain the digest, media type, access rules and retention status. evidence:... strings in the contracts are illustrative managed identities; an existing reference does not prove that its bytes are accessible, fresh, permitted or sufficient. Expiring provider URLs must be copied through the approved Store boundary or the required evidence check cannot pass.

The proposed public pilot excludes login credentials, customer data and account screenshots. Capture only the minimum relevant evidence. The user approved bounded evidence retained for 30 days. Exact byte bounds, access roles and actual runtime/Store enforcement remain prerequisites to live execution. Secret values remain in the approved external secret source; stored definitions contain references only.

Runtime assessment: documentation only

Official documentation and published SDKs checked on 2026-10-16; no SDK/provider execution or account-entitlement test was performed. These are candidates, not verified HKTVmall integrations.

Candidate	Documented foundation	Qualification gap for this pilot
TinyFish	Async submission returns a run ID; status and cancellation support remote lifecycle. Capture and some limits are account-gated. Built-in proxy countries omit HK; Agent custom-proxy prose conflicts with the reviewed API/SDK schema.	Verify capture entitlement, approved HK routing, actual evidence/usage retrieval and enforceable read-only effects. The reviewed submission reference does not establish idempotent creation or unique client-key lookup. Ambiguous submission must stay uncertain until reconciled.
Controlled Stagehand v4	Provides discrete act, extract and observe tools; v4 removed its built-in agent() orchestrator.	Compare a bounded, reviewed navigation/extraction routine. Do not build a new general agent loop or assume a domain allowlist prevents writes.
Browser Use Cloud v4	Run creation accepts optional outputSchema, browser/profile/proxy settings and maxCostUsd.	Qualify schema/SDK behavior, lifecycle cleanup, HK routing, retained evidence and the actual cost/effect enforcement guarantees. An API parameter is not evidence of a strict end-to-end spending cap.

Sources: TinyFish API, TinyFish schema subset, Stagehand v4 migration, Browser Use v4 run creation.

TinyFish is the first hosted candidate to qualify, not an approved default. Its output schema subset excludes several constraints used here, including additionalProperties, const and type arrays. The future adapter must report each omitted/translated rule and always run full canonical validation locally. It must not send the unchanged canonical schema or weaken that schema to fit the provider. Strict/fail-fast prompting is not a read-only security boundary.

Compare the same approved targets and semantics against an available API, deterministic browser extraction, and a direct browser service plus validator. API coverage for the required HKTVmall consumer price is unverified; do not assume an available retailer API has equivalent meaning. Measure reviewed accuracy, accepted coverage, intervention, total cost including failures, publication latency, freshness, recovery reuse and maintenance effort. Expansion depends on an operational benefit, not the number of configuration fields.

Verification boundary

tests/unit/test_agent_price_pilot.py and tests/unit/test_agent_public_offer_pilot.py exercise canonical record validity and demonstrates its limits. tests/integration/test_agent_price_pilot_lifecycle.py and tests/integration/test_agent_public_offer_pilot_lifecycle.py use the existing backend conformance harness for parse → Store → build → validate, including strict cents and unavailable/null after persistence. No test contacts HKTVmall or a browser service. These tests cannot certify remote recovery, read-only enforcement, factual accuracy, retained evidence, freshness, dataset coverage or publication. Their implementation and live qualification remain on the central AGPIPE backlog.