@roshanpadmanabhan/awp-client

Query the agent web. One import, one line, structured facts.

The human web is built for eyes. AWP is the parallel web built for agents — structured facts, semantic search, live confidence scoring. This SDK queries any AWP node with zero configuration.

npm install @roshanpadmanabhan/awp-client

Zero-config usage

import { AWP } from '@roshanpadmanabhan/awp-client'

// No config needed — queries the public node automatically
const awp = new AWP()

const result = await awp.query('who founded Ferrari')

console.log(result.source)            // "cache" or "web"
console.log(result.topic)             // "Ferrari"
console.log(result.facts)             // typed discrete facts
console.log(result.confidence)        // 0.84
console.log(result.confidence_label)  // "high" | "medium" | "low" | "stale"
console.log(result.flag_count)        // 0

First query for a topic: fetches from the web, extracts facts, stores in index (~10–30s). Same query again: instant cache hit (~100ms). Related query: semantic matching finds the same entry without exact keywords.

Using in an AI agent

import { AWP } from '@roshanpadmanabhan/awp-client'

const awp = new AWP()

async function researchAgent(question: string) {
  const result = await awp.query(question)

  // Trust gate — skip stale or low-confidence results
  if (result.confidence_label === 'stale' || result.confidence < 0.45) {
    return { reliable: false, facts: [] }
  }

  // Format facts as context for your LLM
  const context = result.facts
    .map(f => f.claim)
    .join('\n')

  return {
    reliable:   true,
    source:     result.source_url,
    confidence: result.confidence_label,
    context,
  }
}

Custom node

Point at your own self-hosted AWP node:

const awp = new AWP({
  node:    'https://my-awp-node.railway.app',
  timeout: 60000,   // ms — increase for slow first fetches
})

API

new AWP(options?)

interface AWPOptions {
  node?:    string   // default: https://awp-net.up.railway.app
  timeout?: number   // ms, default: 30000
}

awp.query(question)

Search the index. Falls back to the web on cache miss. Returns identical shape either way.

const result: AWPResult = await awp.query('what is machine learning')

awp.getEntry(id)

Fetch a specific entry by UUID.

const entry = await awp.getEntry('3f8a2c...')
// returns AWPResult or null

awp.isHealthy()

Check if the node is reachable.

const ok: boolean = await awp.isHealthy()

Types

interface AWPResult {
  hit:              boolean           // true = cache, false = web fallback
  source:           'cache' | 'web'
  id?:              string            // entry UUID
  topic:            string            // canonical topic label
  facts:            AWPFact[]
  source_url:       string
  fetched_at:       string            // ISO timestamp
  confidence:       number            // 0.0–1.0, live computed
  confidence_label: 'high' | 'medium' | 'low' | 'stale'
  flag_count:       number
  similarity?:      number            // cosine similarity (cache hits)
}

interface AWPFact {
  claim:  string
  type:   'text' | 'numeric' | 'boolean' | 'date'
  value?: string | number | boolean
  unit?:  string
}

Confidence labels

| Label | Score | Meaning | |---|---|---| | high | ≥ 0.85 | Fresh, authoritative source, no flags | | medium | 0.65–0.84 | Good but aging or lower-authority source | | low | 0.45–0.64 | Use with caution — aging or flagged | | stale | < 0.45 | Will trigger re-fetch on next query |

Public node

The default node at awp-net.up.railway.app is free to query with no API key. It is a shared index — every cache miss writes a new entry that benefits all future agents.

Run your own node: github.com/BROODHONEY/awp

License

MIT