{
  "schema_version": "v1",
  "name": "AIFreight Operating System (FreightOS · BondOS · LogisticsOS · AI Clerk)",
  "description": "AI-native UK/SME freight-forwarding, customs-warehousing and fleet operating system. One consignment object flows through four engines: FreightOS (instant multimodal quote with live UK Trade Tariff duty, import VAT, origin-aware preferential duty, multi-currency valuation, real-geography route optimisation, public-index rate bands and OFSI/OFAC sanctions screening); BondOS (customs-warehouse duty + import VAT suspension, stock record, partial draw-down, CCG guarantee headroom, working-capital released); LogisticsOS (O-licence van-fleet job costing, driver-hours + vehicle compliance, load utilisation, dispatch clearance); the AI Clerk (every document at every stage — import, bond, delivery — pre-filled and validated); plus the FMCG funded-cycle layer (Vaping Products Duty + Soft Drinks Industry Levy + the supplier-terms/PVA/deferment/bond/invoice-finance cash-conversion cycle). Decision support — figures are indicative, firmed at booking; regulated/irreversible steps stop at a human gate.",
  "contact": "hello@aifreight.co.uk",
  "base_url": "https://aifreight.co.uk",
  "legal": "Not customs advice. The declarant/operator stays accountable. Freight is indicative; official HMRC customs exchange rates + carrier rates apply at declaration/booking.",
  "tools": [
    {
      "name": "quote_shipment",
      "description": "Price a shipment across road/sea/air on one object: landed cost (duty + import VAT), freight by mode with a route score, cheapest + best-overall picks, customs readiness, sanctions posture. Persists and returns a shareable id.",
      "method": "POST",
      "path": "/api/quote",
      "input_schema": {
        "type": "object",
        "required": [
          "goods_value",
          "weight_kg"
        ],
        "properties": {
          "goods_value": {
            "type": "number",
            "description": "Customs (CIF) value of the goods"
          },
          "currency": {
            "type": "string",
            "description": "ISO currency of goods_value (GBP default). 20 majors supported; converted to GBP at the live ECB rate."
          },
          "weight_kg": {
            "type": "number"
          },
          "volume_m3": {
            "type": "number"
          },
          "commodity_code": {
            "type": "string",
            "description": "6-10 digit HS/commodity code. Use classify_commodity if unknown."
          },
          "origin": {
            "type": "string",
            "enum": [
              "eu",
              "rest",
              "gb"
            ],
            "description": "Origin zone"
          },
          "origin_country": {
            "type": "string",
            "description": "Origin country (name or ISO) — sharpens duty + preferential eligibility + sanctions."
          },
          "origin_locode": {
            "type": "string",
            "description": "Origin UN/LOCODE (e.g. CNSHA Shanghai) — resolves the real port so the lane carries chokepoint exposure, draught limits + customs dwell (port_profile)."
          },
          "dest_locode": {
            "type": "string",
            "description": "Destination UN/LOCODE (e.g. GBFXT Felixstowe). Pair with origin_locode for port-to-port operational nuance."
          },
          "vessel_draught_m": {
            "type": "number",
            "description": "Optional laden draught (m) — flags any port or canal (e.g. Panama 15.2m) the vessel cannot transit."
          },
          "destination": {
            "type": "string",
            "enum": [
              "gb",
              "ni",
              "eu",
              "rest"
            ]
          },
          "incoterm": {
            "type": "string",
            "enum": [
              "DDP",
              "DAP",
              "FCA",
              "EXW",
              "CIF",
              "FOB"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "auto",
              "road",
              "sea",
              "air"
            ],
            "description": "auto = cheapest compliant"
          },
          "vat_rate_pct": {
            "type": "number",
            "enum": [
              20,
              5,
              0
            ],
            "description": "UK import VAT rate (20 standard default)"
          },
          "method": {
            "type": "string",
            "enum": [
              "pva",
              "border",
              "deferment"
            ],
            "description": "VAT accounting method"
          },
          "consignor_name": {
            "type": "string",
            "description": "Shipper name — screened against OFSI"
          },
          "consignee_name": {
            "type": "string",
            "description": "Receiver name — screened against OFSI"
          }
        }
      },
      "returns": "quote object: { quote_ref, id, share_path, duty, landed_cost, options[], recommended, best_overall, lane, customs, screening, compliance_stop, decision }"
    },
    {
      "name": "retrieve_quote",
      "description": "Rehydrate a stored quote by its id (margin-stripped, customer-safe).",
      "method": "GET",
      "path": "/api/quote?id={uuid}"
    },
    {
      "name": "classify_commodity",
      "description": "Find candidate HS/commodity codes from a plain-English goods description (UK Trade Tariff). Use the returned code with quote_shipment for a sourced duty.",
      "method": "GET",
      "path": "/api/classify?q={description}",
      "returns": "candidates[]: { code, description, score }"
    },
    {
      "name": "compare_customs_regimes",
      "description": "Bonded-warehouse decision engine: compare pay-at-border / Postponed VAT Accounting / duty deferment / customs warehousing for one consignment. Quantifies duty suspension over the dwell, re-export duty relief (never paid), VAT cash-flow and the bonded storage premium. Stateless + indicative; duty rate + valuation apply at RELEASE from the warehouse.",
      "method": "POST",
      "path": "/api/bonded-relief",
      "input_schema": {
        "type": "object",
        "required": [
          "customs_value_gbp",
          "duty_pct"
        ],
        "properties": {
          "customs_value_gbp": {
            "type": "number",
            "description": "CIF customs value in GBP"
          },
          "duty_pct": {
            "type": "number",
            "description": "HMRC duty rate % (use classify_commodity + quote_shipment for a sourced rate)"
          },
          "vat_rate": {
            "type": "number",
            "enum": [
              0.2,
              0.05,
              0
            ],
            "description": "import VAT rate (0.20 default)"
          },
          "dwell_days": {
            "type": "number",
            "description": "expected days in bond before release (default 60)"
          },
          "reexport_share": {
            "type": "number",
            "description": "0..1 share re-exported from bond — UK duty never paid on it (default 0)"
          },
          "annual_cost_of_capital": {
            "type": "number",
            "description": "working-capital cost assumption (default 0.08)"
          },
          "bonded_storage_premium_gbp": {
            "type": "number",
            "description": "premium the bonded warehouse charges over standard storage (default 0)"
          },
          "vat_registered": {
            "type": "boolean",
            "description": "default true — unregistered importers cannot use PVA or recover import VAT"
          },
          "vat_recovery_days": {
            "type": "number",
            "description": "days from paying import VAT to recovering it on the return (default 45)"
          },
          "deferment_delay_days": {
            "type": "number",
            "description": "duty-deferment payment delay in days (default 30 — Notice 101, ~15th of the following month)"
          },
          "pva_at_release": {
            "type": "boolean",
            "description": "default true — use Postponed VAT Accounting on the release-from-warehouse declaration (registered importers)"
          }
        }
      },
      "returns": "comparison: { duty_full_gbp, import_vat_full_gbp, regimes[4] (net_advantage_vs_immediate_gbp, requirements, notes), recommended, honesty, source_basis }"
    },
    {
      "name": "bond_movement",
      "description": "BondOS — model goods entering a customs warehouse with import duty + import VAT suspended, an optional partial draw-down (home-use/export/transfer), CCG guarantee headroom, and the working-capital released. Returns the suspended figures + the stock-record ledger. Duty rate/value at removal is confirmed on the CDS declaration (human gate).",
      "method": "POST",
      "path": "/api/bond",
      "input_schema": {
        "type": "object",
        "required": [
          "goods_value"
        ],
        "properties": {
          "goods_value": {
            "type": "number",
            "description": "Customs value of the goods entering the warehouse"
          },
          "duty_rate_pct": {
            "type": "number"
          },
          "vat_rate_pct": {
            "type": "number",
            "enum": [
              20,
              5,
              0
            ]
          },
          "commodity_code": {
            "type": "string"
          },
          "warehouse_type": {
            "type": "string",
            "enum": [
              "private",
              "public"
            ]
          },
          "warehouse_auth": {
            "type": "string",
            "description": "Customs-warehouse authorisation number"
          },
          "guarantee_gbp": {
            "type": "number",
            "description": "CCG reference amount"
          },
          "guarantee_waiver": {
            "type": "boolean"
          },
          "open_liability_gbp": {
            "type": "number",
            "description": "Duty already suspended across the warehouse"
          },
          "days_in_warehouse": {
            "type": "number"
          },
          "pva": {
            "type": "boolean",
            "description": "Postponed VAT Accounting (default true)"
          },
          "removal": {
            "type": "object",
            "description": "{ type: home_use|export|transfer, portion_pct: 0-100, duty_rate_pct? }"
          }
        }
      },
      "returns": "bond object: { warehouse, suspension, removal, guarantee, working_capital, stock_record[], suspended_remaining_gbp, flags[], ready, decision }"
    },
    {
      "name": "logistics_job",
      "description": "LogisticsOS — cost + compliance-check a delivery job for an O-licence fleet: own-fleet cost per mile/per drop + sell rate at margin, driver-hours regime check (EU >3.5t / GB domestic), vehicle compliance (MOT/tax/inspection/tacho/walkaround), O-licence financial standing + vehicle margin, load utilisation, and a dispatch verdict. Statutory sign-off stops at a human gate.",
      "method": "POST",
      "path": "/api/logistics",
      "input_schema": {
        "type": "object",
        "required": [
          "distance_miles"
        ],
        "properties": {
          "distance_miles": {
            "type": "number"
          },
          "drops": {
            "type": "number"
          },
          "international": {
            "type": "boolean"
          },
          "vehicle": {
            "type": "object",
            "description": "{ reg, gvw_kg, payload_kg, volume_m3, mpg, fuel_price_ppl, mot_due, ved_due, safety_inspection_due, tacho_calibration_due, walkaround_due }"
          },
          "load": {
            "type": "object",
            "description": "{ weight_kg, volume_m3 }"
          },
          "driver": {
            "type": "object",
            "description": "{ driving_hours, duty_hours }"
          },
          "licence": {
            "type": "object",
            "description": "{ type: standard|light_goods|restricted, vehicles_authorised, vehicles_in_use, available_finance_gbp }"
          }
        }
      },
      "returns": "job object: { cost, driver_hours, load, compliance, licence, flags[], dispatchable, decision }"
    },
    {
      "name": "clerk_paperwork",
      "description": "AI Clerk — for a consignment + stage (import/bond/delivery/all), return the required document checklist pre-filled from the consignment, what is still missing, and drafts of the structured documents. Pass extras.product_type (vape / soft_drink / energy_drink / wine_spirits) to pull the FMCG bond-clerk documents: EMCS eAD for duty-suspended excise movements, AWRS due-diligence record, vaping duty-stamp compliance record, SDIL quarterly-return line. Regulated filings/signatures carry a human gate; optional AI assist normalises the goods description + drafts a covering note.",
      "method": "POST",
      "path": "/api/clerk",
      "input_schema": {
        "type": "object",
        "properties": {
          "consignment": {
            "type": "object",
            "description": "The shared consignment, or pass its fields at the top level"
          },
          "stage": {
            "type": "string",
            "enum": [
              "import",
              "bond",
              "delivery",
              "all"
            ]
          },
          "extras": {
            "type": "object",
            "description": "Operator details: consignor_name, consignee_name, invoice_no, incoterm, eori, description, warehouse_auth, delivery_address, vehicle_reg, claim_preference …"
          },
          "draft": {
            "type": "string",
            "description": "A single document key to draft in full"
          },
          "ai": {
            "type": "boolean",
            "description": "Request the optional AI-assist pass"
          }
        }
      },
      "returns": "pack: { ucr, stage, documents[]:{ name, stage, authority, human_gate, fields[], missing[], status }, summary, ai_assist? }"
    },
    {
      "name": "dispatch_pack",
      "description": "AI fleet dispatcher — consignment + job → the complete dispatch pack: LogisticsOS verdict (cost/sell, driver-hours, vehicle + O-licence compliance, load), delivery paperwork (delivery note/CMR, POD spec, walkaround) pre-filled by the AI Clerk, a step-by-step driver brief with timing legs, and an honest dispatch_ready flag that never goes green past a blocker. Statutory sign-offs (walkaround, POD, driver hours, bonded release) stay human gates.",
      "method": "POST",
      "path": "/api/dispatch",
      "input_schema": {
        "type": "object",
        "required": [
          "job"
        ],
        "properties": {
          "job": {
            "type": "object",
            "description": "LogisticsOS body: { distance_miles (required), drops, vehicle{}, load{}, driver{}, licence{} }"
          },
          "consignment": {
            "type": "object",
            "description": "the shared consignment (ucr, goods_value, weight_kg, mode, origin, destination)"
          },
          "extras": {
            "type": "object",
            "description": "delivery_address / drop_addresses[], pickup_address, bonded_collection (adds a human-gated release leg), consignor_name, consignee_name, description, vehicle_reg, driver"
          }
        }
      },
      "returns": "pack: { logistics, documents[], docs_summary, brief: { legs[], est_total_hours, drops }, blockers[], dispatch_ready, decision }"
    },
    {
      "name": "fmcg_funded_cycle",
      "description": "FMCG import cashflow + compliance for one consignment — vapes (Vaping Products Duty £2.20/10ml from 1 Oct 2026, duty stamps mandatory 1 Apr 2027, excise suspension separate from customs warehousing), soft drinks (SDIL bands + quarterly-return cashflow, Jan 2028 reform), and the full cash-conversion-cycle runway: negotiated supplier terms + PVA + duty deferment + bonded/excise suspension + invoice finance vs the unstructured baseline. Returns duty plan + compliance timeline + day-by-day cash ledger with peak funding requirement before/after the stack.",
      "method": "POST",
      "path": "/api/fmcg",
      "input_schema": {
        "type": "object",
        "required": [
          "product_type",
          "goods_cost_gbp"
        ],
        "properties": {
          "product_type": {
            "type": "string",
            "enum": [
              "vape",
              "soft_drink",
              "other"
            ]
          },
          "goods_cost_gbp": {
            "type": "number",
            "description": "supplier invoice value (GBP)"
          },
          "on_date": {
            "type": "string",
            "description": "YYYY-MM-DD — rates + timeline statuses computed for this date (default today)"
          },
          "liquid_ml": {
            "type": "number",
            "description": "vape: total ml of vaping liquid"
          },
          "litres": {
            "type": "number",
            "description": "soft_drink: total litres"
          },
          "sugar_g_per_100ml": {
            "type": "number",
            "description": "soft_drink: total sugar per 100ml"
          },
          "milk_based": {
            "type": "boolean",
            "description": "soft_drink: exempt until Jan 2028"
          },
          "customs_duty_gbp": {
            "type": "number"
          },
          "import_vat_gbp": {
            "type": "number"
          },
          "freight_cost_gbp": {
            "type": "number"
          },
          "sale_value_gbp": {
            "type": "number"
          },
          "supplier_terms_days": {
            "type": "number",
            "description": "negotiated supplier payment terms (default 0)"
          },
          "transit_days": {
            "type": "number"
          },
          "days_to_sell": {
            "type": "number"
          },
          "debtor_days": {
            "type": "number"
          },
          "pva": {
            "type": "boolean",
            "description": "default true"
          },
          "dda": {
            "type": "boolean",
            "description": "duty deferment account (default false)"
          },
          "bonded": {
            "type": "boolean",
            "description": "customs warehouse — customs duty at removal (default false)"
          },
          "excise_suspended": {
            "type": "boolean",
            "description": "excise warehouse/approved store — excise at removal (default false; a customs warehouse alone does NOT suspend VPD)"
          },
          "invoice_finance": {
            "type": "boolean",
            "description": "default false"
          },
          "advance_pct": {
            "type": "number",
            "description": "invoice-finance initial advance % (default 85, max 95)"
          }
        }
      },
      "returns": "plan: { on_date, product_type, duty_plan (VPD or SDIL), compliance.items[], runway: { stacked.events[], baseline, working_capital_released_gbp, coverage_pct, funding_gap_gbp, self_funding, invoice_finance_advance_gbp, summary } }"
    },
    {
      "name": "vehicle_lookup",
      "description": "Auto-fill a LogisticsOS vehicle from its UK registration — DVLA Vehicle Enquiry Service (tax + MOT status/expiry, revenue/gross weight, fuel, CO2) enriched with DVSA MOT History (latest result, mileage, advisories). Returns the vehicle object ready to drop into logistics_job. Official data, may lag — confirm before dispatch.",
      "method": "GET",
      "path": "/api/vehicle?reg={registration}",
      "returns": "vehicle: { reg, make, gvw_kg, fuel_type, tax_status, mot_status, mot_due, ved_due, latest_mot_result, advisories[], flags[] }"
    },
    {
      "name": "live_rates",
      "description": "LIVE multi-carrier rates for a shipment via a carrier aggregator (EasyPost by default — 100+ carriers incl. DHL/UPS/FedEx/Royal Mail, no per-carrier contract). Returns the real buy cost per carrier/service + our reseller sell price, cheapest + fastest picks. Turns the indicative FreightOS quote into a live-bookable one. Degrades to indicative when unconfigured; booking + label is a separate human-gated step.",
      "method": "POST",
      "path": "/api/rates",
      "input_schema": {
        "type": "object",
        "properties": {
          "from": {
            "type": "object",
            "description": "{ country, postcode, city, street }"
          },
          "to": {
            "type": "object",
            "description": "{ country, postcode, city, street }"
          },
          "weight_kg": {
            "type": "number"
          },
          "dims_cm": {
            "type": "object",
            "description": "{ l, w, h }"
          },
          "value": {
            "type": "number"
          }
        }
      },
      "returns": "rates: { available, options[]:{ carrier, service, buy_cost, sell_floor, transit_days }, cheapest, fastest }"
    }
  ],
  "capabilities": [
    "live UK Trade Tariff duty (erga-omnes MFN)",
    "origin-aware preferential duty (real geographical-area membership + proof-of-origin gate)",
    "import VAT 20/5/0 with an honesty flag",
    "multi-currency customs valuation (live ECB rate)",
    "public freight-rate-index bands (FBX / BAI / RHA) on every freight figure",
    "real-geography multimodal route optimiser with chokepoint (Suez/Panama/Malacca) disruption",
    "OFSI + OFAC + UN + EU sanctions party-name screening (distinctive-core fuzzy match across the four consolidated lists, hard compliance stop)",
    "commodity-code classification",
    "bonded-warehouse decision: pay-at-border vs PVA vs deferment vs customs-warehousing, quantified for one consignment (decide → then operate with the bond engine)",
    "customs-warehouse duty + import VAT suspension, stock record, partial draw-down (CDS 7100/4071), CCG guarantee headroom, working-capital released",
    "O-licence van-fleet job costing, driver-hours (EU/GB) + vehicle compliance, load utilisation, dispatch clearance",
    "vehicle auto-fill from registration (DVLA VES + DVSA MOT History — tax/MOT/gross-weight/advisories)",
    "live multi-carrier rates via aggregator (EasyPost/DHL/UPS/FedEx) — indicative FreightOS quote becomes live-bookable, reseller margin applied",
    "AI Clerk paperwork across import/bond/delivery — checklist, field pre-fill, structured drafts, human-gated filings",
    "FMCG duty layer: Vaping Products Duty (from 1 Oct 2026, stamps + excise-suspension aware) + Soft Drinks Industry Levy (bands, quarterly-return cashflow, 2028 reform)",
    "funded cash-conversion cycle: supplier terms + PVA + DDA + bond/excise suspension + invoice-finance sizing — peak cash need before/after the stack",
    "one shared consignment object (WCO DUCR-shaped UCR) joining quote → bond → fleet → documents",
    "human gates on: live price, production deploy, partner send, regulated filing (CDS declaration, POD, walkaround), insurance bind"
  ]
}