Skip to content

Getting Started

Jump to bottom
Dusan Milicevic edited this page Apr 24, 2026 · 2 revisions

Getting Started

From zero to a pipeline-validated flight booking in under 10 minutes.

Prerequisites

  • Node.js >= 24 — required for native fetch and ESM
  • pnpm 10+ — workspace monorepo manager
node --version   # v24.x.x
pnpm --version   # 10.x.x

1. Clone and Install

git clone https://github.com/telivity-otaip/otaip.git
cd otaip
pnpm install --frozen-lockfile

This installs all 16 workspace packages: @otaip/core, @otaip/connect, @otaip/adapter-duffel, the CLI, the reference OTA, and every agent package.

Lifecycle scripts are disabled (ignore-scripts=true in .npmrc) for supply-chain safety, so no postinstall runs automatically. The airport reference data is fetched via an explicit step below.

2. Download Reference Data

pnpm run data:download

Fetches airport reference data into data/reference/. Required for the airport-code resolver and any agent that depends on it. Re-run whenever the upstream OurAirports dataset is updated.

3. Build

pnpm build

Builds all packages with tsup in dependency order.

4. Run the Tests

pnpm test

Expect 3,092 tests passing across all packages. Adapter tests use mocked HTTP — no live API calls.

5. Set Up a Duffel Sandbox (optional, for live NDC)

  1. Create a free account at duffel.com
  2. Go to the dashboard and copy the test-mode API token (prefix duffel_test_)

6. Create .env

At the repo root:

# Required for the LLM-orchestrated pipeline demo
ANTHROPIC_API_KEY=sk-ant-...

# Optional: for the Duffel live adapter
DUFFEL_API_KEY=duffel_test_...

The ANTHROPIC_API_KEY drives the tool-calling loop in the full pipeline demo.

7. Run the Full Pipeline Demo

pnpm --filter @otaip/demo book:full

This runs demo/book-flight-full.ts — a complete search-to-book flow with Claude as the orchestrator.

What the pipeline does

  1. Initializes 5 contracted agents: AvailabilitySearch (1.1), FareRuleAgent (2.1), GdsNdcRouter (3.1), PnrBuilder (3.2), PnrRetrieval (3.8)
  2. Bridges each agent to a ToolDefinition via agentToTool() — contract Zod schemas become Anthropic tool input schemas
  3. Opens a pipeline session with an intent lock (e.g. LHR → AMS, economy, one-way)
  4. Claude receives the tools and issues tool_use calls
  5. Every invocation runs through 6 gates:
    • Intent Lock — agent is relevant and intent hasn't drifted
    • Schema In — Zod safeParse on input
    • Semantic In — domain validator (airport codes, future dates, etc.)
    • Cross-Agent — input is consistent with prior outputs in the session
    • Schema Out + Confidence — output passes schema and meets the confidence floor
    • Action Classification — irreversible mutations require approval
  6. Every execution is logged as an agent.executed event on the EventStore

What the LLM cannot do

  • Hallucinate offer IDs — schema gate rejects unknown references
  • Change the destination mid-flow — intent lock blocks it
  • Ticket without prior state — cross-agent gate catches missing offer/PNR
  • Proceed on low confidence — confidence gate rejects

8. Run the Reference OTA

pnpm --filter @otaip/ota-example dev

A Fastify server with a plain HTML/JS frontend comes up on http://localhost:3000. The OTA exposes /api/search, /api/offers/:id, /api/book, /api/pay, /api/ticket, /api/booking/:ref, and /api/cancel. By default it uses a mock in-process adapter; set ADAPTERS=duffel-mock (or duffel) to route through the real Duffel adapter.

See Reference OTA for the full walkthrough.

Useful Commands

Command Description
pnpm build Build all 16 packages
pnpm test Run the full 3,092-test suite
pnpm lint ESLint + Prettier
pnpm --filter @otaip/core test Test only @otaip/core
pnpm --filter @otaip/demo book:full Full pipeline demo
pnpm --filter @otaip/ota-example dev Reference OTA with hot reload

Next

Clone this wiki locally