FAQ

Common questions and solutions.

General

What makes FOON different from other JSON transformation libraries?

FOON combines AI-powered semantic understanding with deterministic execution:

  • Traditional libraries require you to write explicit mapping rules
  • Pure AI approaches can produce unpredictable outputs
  • FOON uses AI only for understanding, then executes deterministically

Is FOON production-ready?

Yes. FOON is designed for production use with:

  • Mandatory schema validation
  • Deterministic transforms (no AI randomness in execution)
  • Caching for performance
  • Comprehensive error handling
  • Security features (redaction, limits)

How much does FOON cost?

The FOON SDK is free and open source (ISC license).

Costs come from your AI provider:

  • Each new mapping plan requires one AI call
  • Cached plans don't require AI calls
  • Typical cost: $0.01-0.05 per unique schema shape

Technical

How does caching work?

FOON caches mapping plans based on:

  1. Input structure (field names, nesting, types)
  2. Target schema

The first request for a new input shape generates a plan (~500-2000ms). Subsequent requests with similar structure use the cached plan (~5-50ms).

import { transform, OpenAIProvider, LRUCache } from 'foon-sdk';

const cache = new LRUCache({ max: 100, ttl: 3600000 });

const result = await transform(input, {
  schema,
  provider: new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-5-nano'
  }),
  cache
});

console.log('Cache hit:', result.trace.cache.hit);

What if the AI generates a wrong mapping?

Several safeguards exist:

  1. Schema validation - Output must match your schema
  2. Confidence scores - Low-confidence mappings can be rejected
  3. Trace output - Full visibility into mapping decisions
const result = await transform(input, {
  schema,
  provider,
  confidenceThreshold: 0.9  // Reject low-confidence mappings
});

if (!result.ok && result.error?.category === 'CONFIDENCE_TOO_LOW') {
  console.log('Rejected:', result.trace.execution.assignmentsRejected);
}

Can I use FOON without an external AI provider?

Yes, use Ollama for self-hosted AI:

import { transform, OllamaProvider } from 'foon-sdk';

const result = await transform(input, {
  schema,
  provider: new OllamaProvider({
    model: 'llama2',
    baseUrl: 'http://localhost:11434'
  })
});

Does FOON support nested arrays?

Yes. FOON handles:

  • Nested objects
  • Arrays of primitives
  • Arrays of objects
  • Deeply nested structures

Troubleshooting

Transform is slow

Cause: No cached mapping plan

Solution: Enable caching:

import { transform, OpenAIProvider, LRUCache } from 'foon-sdk';

const cache = new LRUCache({ max: 100, ttl: 3600000 });

const result = await transform(input, {
  schema,
  provider: new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-5-nano'
  }),
  cache
});

Validation keeps failing

Cause: Output doesn't match schema

Solution: Check your schema definition and use the trace:

const result = await transform(input, { schema, provider });

if (!result.ok) {
  console.log('Error:', result.error?.category);
  console.log('Validation:', result.trace.validation);
  console.log('Mapping plan:', result.trace.mappingPlan);
}

Low confidence scores

Cause: Field names are ambiguous

Solution: Lower the threshold for testing, or use more descriptive field names:

// For testing/debugging
const result = await transform(input, {
  schema,
  provider,
  confidenceThreshold: 0.7,  // Lower threshold
  verbose: true               // More debug output
});

console.log('Confidence summary:', result.trace.confidenceSummary);

Provider errors

Cause: API issues with your AI provider

Solution: Check API key and handle errors:

const result = await transform(input, { schema, provider });

if (!result.ok && result.error?.category === 'PROVIDER_ERROR') {
  console.log('Provider error:', result.error.message);
  // Retry or fallback logic
}

Migration

From manual mapping code

Replace explicit mappings with FOON:

// Before: Manual mapping
function transformCustomer(input) {
  return {
    name: {
      given: input.fullName?.split(' ')[0],
      family: input.fullName?.split(' ')[1]
    },
    email: input.email_addr || input.emailAddress
  };
}

// After: FOON
import { transform, OpenAIProvider } from 'foon-sdk';

const result = await transform(webhookData, {
  schema: customerSchema,
  provider: new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-5-nano'
  })
});

if (result.ok) {
  const customer = result.output;
}

From other transformation libraries

FOON is additive - use it alongside existing tools:

// Use FOON for dynamic/unpredictable inputs
if (isKnownFormat(input)) {
  return existingTransform(input);
} else {
  const result = await transform(input, { schema, provider });
  return result.ok ? result.output : null;
}