Install and try offline

Requires Python 3.12 or later. From a fresh terminal:

python -m pip install "git+https://github.com/LKennedyShare/irish-car-import-assistant.git"
car-import-assistant --demo

The demo is labelled SYNTHETIC_OFFLINE_DEMO. Its figures and comparable counts are illustrative, not live findings. It uses no network, wallet or payment signing. python -m irish_car_import_assistant accepts the same arguments as the console command.

Run a free comparison

For a guided free comparison:

car-import-assistant --interactive

Enter the actual car details and CO2 figure, then type compare to authorize a free request. Do not guess CO2 or the underlying fuel of a hybrid.

Or provide structured input:

car-import-assistant --make Volkswagen --model Golf --year 2023 --mileage-km 50000 --fuel-type Petrol --co2-g-km 125

Add --json for one machine-readable result, --origin GB or --origin NI to restrict the route, or --transmission Automatic. The default origin is ANY. Coverage changes; this example is not a promise of matching live stock.

Supported fuels: Petrol, Diesel, Electric, Petrol Hybrid, Diesel Hybrid, Petrol Plug-in Hybrid and Diesel Plug-in Hybrid.

The service’s default preview allowance is 3 attempts per UTC day per IP, shared with its REST and MCP callers. No-data and invalid attempts may consume the allowance. A quota failure never triggers a paid upgrade. HTTP 429 errors preserve Retry-After; errors go to stderr with a nonzero exit.

The output explains the Irish median and comparable count, route totals, savings or shortfall, transport, customs, VAT, VRT, NOx and other costs. Individual listing links are reserved for the full paid result.

Inspect or explicitly pay for full results

Repeat a structured command with --full to inspect its quote without paying. An ordinary MCP connection does not supply a wallet or payment capability.

For a paid result, set X402_CLIENT_PRIVATE_KEY in your local shell to a throwaway wallet funded with only a small USDC balance on the quoted network, then explicitly authorize:

car-import-assistant --make Volkswagen --model Golf --year 2023 --mileage-km 50000 --fuel-type Petrol --co2-g-km 125 --full --pay --max-usdc 0.02

Never put the private key in source code, request JSON, prompts, logs or this repository. Base mainnet uses real USDC.

Only --full --pay authorizes one capped paid retry. There are no automatic payment retries, and redirects are refused. Only exact USDC on Base and Base Sepolia is accepted. A missing settlement response is explicitly unconfirmed, not proof that payment succeeded. Each invocation has its own cap; this is not a daily wallet spending limit.

No command buys a car, pays an invoice, executes an import or follows listing links. The result is advisory, not tax, customs or financial advice. Asking prices are not sale prices. Independently confirm vehicle history, bank details, FX, duty/VAT eligibility, Revenue OMSP/VRT and NOx before buying.

Use from another agent

from irish_car_import_assistant import compare_car

result = compare_car(
    make="Volkswagen", model="Golf", year=2023,
    mileage_km=50000, fuel_type="Petrol", co2_g_km=125,
)
print(result["verdict"], result["routes"])

This defaults to a free preview. full=True inspects a quote; payment also requires pay=True and accepts max_usdc="0.02". Errors are surfaced as ValueError or httpx.HTTPError rather than invented comparisons.

--base-url can target another compatible HTTPS service; HTTP is allowed only on localhost/loopback. Requests identify as car-import-assistant. That label is not evidence that a caller is a genuine independent customer.

Development

git clone https://github.com/LKennedyShare/irish-car-import-assistant.git
cd irish-car-import-assistant
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test]"
python -m pytest -q

Tests mock HTTP and payments. Test/release jobs run tests and the offline demo only; they do not use a wallet or make paid requests.

Release and unpaid discovery automation

PyPI publication is pending owner authorization, not configured or published. Keep using the GitHub installation above until the first PyPI publication. The owner must sign in at https://pypi.org/manage/account/publishing/ and create this one-time pending trusted publisher:

• PyPI project: irish-car-import-assistant

• GitHub owner: LKennedyShare

• Repository: irish-car-import-assistant

• Workflow filename: publish.yml

• Environment: pypi (exact, fixed GitHub environment name)

The owner must also create that GitHub environment. No API token or password is used. No manual approval per release is required by default; environment protection rules can impose approval if the owner chooses. After setup, publishing a GitHub release tagged v0.1.1 builds the current version’s wheel and sdist, runs mocked tests, the installed offline CLI and strict Twine checks, then publishes via OIDC. Only release.published triggers publication, not a PR or manual workflow run. Tags must exactly match v<pyproject.version> and package identity is checked before build. PyPI versions are immutable: future releases need a new version and matching tag. Duplicate uploads fail rather than silently skipping existing files. Current version remains 0.1.1 for the first publication.

discovery.yml runs nightly at 03:23 UTC and supports manual dispatch. It uses Python’s standard library only, no SDK, wallet, secrets or funds. It reads public health/OpenAPI/cards/homepage/buyers metadata and sends one unsigned paid REST quote probe and one empty-arguments MCP quote probe. It never calls the free preview, signs, pays, changes listings or follows response URLs. The car service uses REST/MCP, not the A2A protocol. All requests identify as scout-distribution-monitor: diagnostics, not customers, purchases, demand or independent adoption.

Run locally with python scripts/check_discovery.py --service car --output discovery.json. The JSON, Actions artifact and step summary contain only fixed check names and statuses, never response bodies, headers or private data. Requests refuse redirects, cap bodies at 2 MB and use 15-second socket timeouts; failures exit nonzero. A missing PyPI project is explicitly pending, without masking service failures. After publication add --require-pypi to the workflow’s monitor command to enforce PyPI availability and repository/MIT/name metadata. The homepage and /buyers.txt must link this public client repository.

GitHub schedules can be delayed or dropped and public-repository schedules may be disabled after 60 days without repository activity. This is not guaranteed continuous uptime monitoring; review Actions and re-enable schedules when needed. No artificial activity, stars or promotional posting is generated.

Licensing

MIT licensed; see LICENSE. This covers this buyer client’s source code, not the separate service, its data or its API usage terms.