@carbonaa/aoi-sdk

Zero-dependency JavaScript / TypeScript client for the AOI (Agent-Oriented Intelligence) environmental intelligence platform by Carbonaa SA.

AOI delivers environmental decision intelligence to AI agents. External AI agents discover capabilities, request a commercial quote, and execute against real environmental data — receiving structured intelligence, evidence, and provenance they can act on.

• Agent-to-agent, quote-first commercial model — no subscriptions, no pricing changes.
• Real data, never fabricated — capabilities reason over approved data sources (e.g. SatClimate signals). If a required data source is unavailable, the call fails honestly.
• Prepaid credit ledger — agents fund a USD balance and consume it per successful execution.
• Zero runtime dependencies — works in Node 18+, browsers, Deno, and edge runtimes.

Installation

npm install @carbonaa/aoi-sdk

Or without a package manager (the SDK is a single file):

curl -sL "https://carbonaa.org/functions/aoiSdkDistribution?file=aoi.js" -o aoi.js

What is AOI?

AOI (Agent-Oriented Intelligence) is an independent environmental intelligence platform that lets external AI agents obtain rigorous, evidence-backed environmental analysis on demand — climate risk, carbon integrity, methane compliance, industrial monitoring, and more. Agents do not get raw data dumps; they get decision intelligence: a structured result with a risk score, confidence, findings, recommendations, evidence references, scientific explanation, and data provenance.

The commercial model is quote-first: an agent requests a quote for a capability + input, reviews the price, then executes. A quote is not intelligence and is not charged. Only a successful execution deducts from the agent's prepaid balance.

Authentication

AOI uses AOI-native API keys (not OAuth). Obtain a key in the Agent Console after agent registration. Pass it via the X-API-Key header — the SDK does this for you when you set apiKey.

import { AoiClient } from "@carbonaa/aoi-sdk";
const aoi = new AoiClient({ apiKey: process.env.AOI_API_KEY });

The key is sent only to the AOI gateway (https://carbonaa.org/functions/aoiAgentServiceGateway). Never embed a production key in client-side code that ships to end users.

Catalog discovery

The catalog lists every sellable capability with its commercial price, scientific domain, confidence target, and whether it requires real data.

const catalog = await aoi.catalog();
for (const c of catalog.capabilities) {
  console.log(c.capability_id, c.commercial_price, c.requires_real_data);
}

Requesting a quote

A quote commits to a price for a specific input. It is valid for 15 minutes. Requesting a quote does not execute anything and does not charge.

const quote = await aoi.quote("climate_risk.asset_exposure", { lat: 51.5, lon: 0.1 });
console.log(quote.quote_id, quote.price, quote.valid_until);

Authorization is fully automatic and server-side. If the quote is within the agent's prepaid balance and spending policy, execution proceeds without any human action. quote.requires_approval is always false (retained for backward compatibility) — no human approval is ever required.

Executing a capability

Execution runs the capability over real data (when the capability requires it) and returns structured intelligence. On success, the quote price is deducted from the agent's prepaid balance.

const result = await aoi.execute(quote.quote_id, { lat: 51.5, lon: 0.1 });
console.log(result.transaction_id, result.confidence, result.real_data_used);
console.log(result.result);       // { result_summary, risk_score, findings, recommendations, ... }
console.log(result.provenance);   // evidence sources

The input data passed to execute must match the input passed to quote (a request hash is enforced). To change the analysis, request a new quote.

Receiving intelligence, evidence & provenance

A successful execution returns:

| Field | Meaning | |---|---| | result.result_summary | Plain-language findings | | result.risk_score | 0–100 | | result.confidence | 0–100 (lowered when real data is sparse) | | result.findings | Discrete findings, each grounded in evidence where available | | result.recommendations | Actionable next steps | | result.evidence_refs | Signal IDs cited from real data | | result.scientific_explanation | Methodology | | result.data_freshness | "real", "stale", or "model_only" | | provenance | Array of evidence sources (source, provider, source_id, freshness) |

Internal fields (delivery cost, margin, profit, connection IDs) are never exposed to the agent.

Other actions

await aoi.health();                              // gateway health & feature list
await aoi.getQuote(quote_id);                    // re-fetch a quote
await aoi.getTransaction(transaction_id);        // settlement + provenance
await aoi.account();                             // balance, limits, keys, recent txns
await aoi.usage(20);                             // last 20 transactions

No customer-facing refunds. AOI does not provide a public refund mechanism. Prepaid credit is consumed to execute capabilities. Internal ledger corrections (e.g. duplicate debit) are performed admin-only and are not exposed through the SDK.

Error handling

All non-2xx responses throw an AoiError with code, status, and retryable:

import { AoiClient, AoiError } from "@carbonaa/aoi-sdk";
try {
  await aoi.execute(quoteId, input);
} catch (e) {
  if (e instanceof AoiError) {
    console.error(e.code, e.status, e.message, e.retryable);
    if (e.status === 402 && e.code === "CREDIT_EXPIRED") { /* buy credits */ }
    if (e.status === 429) { /* wait and retry — e.retryable === true */ }
  }
}

Common error codes: AUTHENTICATION_REQUIRED, INVALID_CREDENTIAL, CAPABILITY_NOT_FOUND, INSUFFICIENT_CREDIT, CREDIT_EXPIRED, SINGLE_TRANSACTION_LIMIT_EXCEEDED, DAILY_SPENDING_LIMIT_EXCEEDED, MONTHLY_SPENDING_LIMIT_EXCEEDED, CAPABILITY_NOT_ALLOWED, QUOTE_EXPIRED, QUOTE_ALREADY_CONSUMED, QUOTE_REQUEST_MISMATCH, RATE_LIMITED, PROVIDER_TIMEOUT, DATA_UNAVAILABLE. No approval_required is ever returned for a normal transaction.

Retryable errors (429, 503, 504) set retryable: true. Use the same idempotency_key on retries to avoid duplicate work.

Full example

See examples/quickstart.mjs (JavaScript) and examples/quickstart.ts (TypeScript).

import { AoiClient } from "@carbonaa/aoi-sdk";
const aoi = new AoiClient({ apiKey: process.env.AOI_API_KEY });

const catalog = await aoi.catalog();
const cap = catalog.capabilities[0];
const quote = await aoi.quote(cap.capability_id, { lat: 51.5, lon: 0.1 });
const result = await aoi.execute(quote.quote_id, { lat: 51.5, lon: 0.1 });
console.log(result.confidence, result.result.result_summary);

Compatibility & architecture

• Runtime: Node 18+, modern browsers, Deno, edge workers. Uses fetch + AbortController (global in all supported runtimes).
• No dependencies. The package ships aoi.js (ESM) + aoi.d.ts (types).
• Connects to the production AOI gateway at https://carbonaa.org/functions/aoiAgentServiceGateway. It does not bypass the catalog → quote → authorization → execution → provenance → settlement architecture; it is a thin client over that exact flow.

License

MIT © Carbonaa SA