AI Module

The Angstroma AI module provides nine content transform functions powered by Claude. Each function is designed for accessibility use cases: reducing reading level, generating image descriptions, scaffolding learning support, and adapting content for different learning needs.

Credit-pool tiers

Each monthly tier grants a pool of credits that AI tasks draw from. You can change tiers at any time — Stripe prorates to the day. Enterprise contracts may negotiate custom pool sizing.

Smart Mode — pick your Claude model per task

Every transform accepts an optional mode parameter that selects which Claude tier runs the request. Credits are consumed as a multiplier of the Standard cost:

Your tenant has a Smart Mode cap set by the owner. Requests above the cap return403 SmartModeCapExceeded without consuming credits. Default cap is Standard.

Sending Smart Mode via the API

# Simplify with Sonnet (3 credits instead of 1)
curl -X POST https://api.angstroma.com/api/v1/content/simplify \
  -H "X-Api-Key: ang_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...",
    "targetGradeLevel": 5,
    "mode": 1
  }'

Overage & spend cap

If you exhaust your monthly pool, further tasks are billed as metered overage at approximately $0.015 per credit. You set a monthly overage cap in Billing — default is $50 USD. Set it to $0 to hard-block overage; above the cap the API returns 429 AiCapReached. Email alerts fire at 80% and 100% of both pool and cap.

Cache & free hits

All AI responses are cached by a SHA-256 hash of (content + transform + target level + mode)for 7 days. Cache is partitioned by Smart Mode tier, so Haiku and Opus outputs never mix. Cache hits return wasCached: true and consume zero credits. Building cache-friendly requests (stable input text, same grade level, same mode) maximises hit rate.

Currency & billing

AI credit-pool and any overage are always billed in USD via Stripe, globally. This applies even to tenants whose base plan is billed in LKR via PayHere — AI pricing stays uniform worldwide and avoids FX drift on metered usage.

Available transforms

Response format

All AI transform endpoints return the same structure:

{
  "result": "...",     // the transformed content
  "wasCached": false,  // true if served from cache
  "tokensUsed": 84     // Claude tokens consumed (0 if cached)
}

Usage examples

Via React SDK

import { simplify, generateAltText, getHints } from '@angstroma/a11y-sdk'
import { useA11y } from '@angstroma/a11y-sdk'

function ContentCard({ passage, image, question, answer }) {
  const { client } = useA11y()

  // Simplify reading level
  const simple = await simplify(client, {
    text: passage,
    targetGradeLevel: 5,
  })

  // Generate alt text
  const alt = await generateAltText(client, {
    imageUrl: image,
    context: 'Science textbook diagram',
  })

  // Get hints without revealing the answer
  const hints = await getHints(client, {
    question,
    correctAnswer: answer,
    gradeLevel: 7,
    subject: 'math',
  })
}

Via Vanilla JS SDK

import { AngstromaA11y } from '@angstroma/a11y-sdk'

const a11y = new AngstromaA11y({ apiKey: 'ang_live_YOUR_KEY' })
await a11y.mount()

const simplified = await a11y.simplify(longPassage, 5)
const altText = await a11y.generateAltText(imageUrl, 'Context hint')
const hints = await a11y.getHints(question, answer, { gradeLevel: 8 })

Via REST API directly

# Translate to Spanish
curl -X POST https://api.angstroma.com/api/v1/content/translate \
  -H "X-Api-Key: ang_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to today\'s lesson on fractions.",
    "targetLanguage": "es"
  }'

# OCR — extract text from image
curl -X POST https://api.angstroma.com/api/v1/content/ocr \
  -H "X-Api-Key: ang_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/worksheet.png"
  }'

Rate limits & quotas