@cyclecore/maaza

Fast, accurate JSON extraction using small language models.

75.7% accuracy • Runs anywhere • 100 free requests to start

🚀 Quick Start

Installation

npm install @cyclecore/maaza

Cloud Mode (Recommended - Fast & Production-Ready)

⚡ Get 100 free requests instantly (no signup): cyclecore.ai/research

import { maaza } from '@cyclecore/maaza/cloud';

// Set your API key
process.env.MAAZA_API_KEY = 'your_api_key_here';

// Extract JSON from any text
const result = await maaza(
  "Invoice #12345 from Acme Corp for $599.99 dated November 27, 2025",
  {
    invoice_id: "string",
    company: "string",
    amount: "number",
    date: "string"
  }
);

console.log(result);
// → { invoice_id: "12345", company: "Acme Corp", amount: 599.99, date: "November 27, 2025" }

Performance:

• ⚡ 400-800ms latency (cloud API)
• ✅ 75.7% accuracy on EdgeJSON benchmark
• 🔒 HTTPS + authentication
• 📊 Usage tracking + quota management

Local Mode (Coming Soon - Offline & Free)

Note: Local mode (v1.5.0) will use Maaza-360M v1.0 model via ONNX runtime for offline extraction.

import { maaza } from '@cyclecore/maaza';

const result = await maaza(
  "Order #789 by Sarah Johnson for 3 items at $149.99",
  {
    order_id: "string",
    customer: "string",
    quantity: "number",
    total: "number"
  }
);

console.log(result);
// → { order_id: "789", customer: "Sarah Johnson", quantity: 3, total: 149.99 }

Notes:

• 📦 First run downloads model (~700MB, cached forever)
• ⏱️ Latency varies by runtime (coming in v1.5.0)
• 🔌 Works offline after first download
• 🌐 Runs in Node.js, Bun, Deno, browser (WebGPU)

📖 API Reference

maaza(text, schema, options?)

Extract structured JSON from unstructured text.

Parameters:

• text (string): Input text to extract from
• schema (object): Field definitions { field_name: "type" }
  • Supported types: "string", "number", "boolean", "array", "object"
• options (optional):
  • apiKey (string): API key for cloud mode (or use MAAZA_API_KEY env var)
  • model (string): Model to use (maaza-slm-360m [default] or maaza-mlm-135m)
  • temperature (number): Sampling temperature (0.1-1.0, default: 0.3)

Returns: Promise<Record<string, any>> - Extracted JSON object

Throws: Error if extraction fails or API key is invalid

🎯 Use Cases

✅ Invoices & Receipts

const invoice = await maaza(
  "INVOICE\nAcct Corp\nInvoice #: INV-2025-007\nAmount: $1,299.00\nDue: Dec 15, 2025",
  { invoice_number: "string", company: "string", amount: "number", due_date: "string" }
);

✅ Emails & Messages

const meeting = await maaza(
  "Hi! Let's meet next Tuesday at 2pm at the downtown office. -John",
  { day: "string", time: "string", location: "string", sender: "string" }
);

✅ Forms & Documents

const resume = await maaza(
  "John Smith\nSoftware Engineer\n5 years experience\nPython, TypeScript, React",
  { name: "string", title: "string", experience: "string", skills: "string" }
);

💰 Pricing

| Tier | Price | Requests | Best For | |------|-------|----------|----------| | ⚡ Instant | FREE | 100 (no signup) | Quick tests, demos | | 🆓 Free | $0/mo | 1,000/mo | Side projects, learning | | 💼 Starter | $79/mo | 10,000/mo | Small apps, startups | | 🚀 Pro | $299/mo | 50,000/mo | Production apps | | 🏢 Enterprise | Custom | Custom | High volume |

Get started: cyclecore.ai/research
Local mode: Coming in v1.5.0 (unlimited, free, offline)

🔧 Advanced Usage

Cloud Mode - Full Response

Get metadata (tokens, latency, validation):

import { maazaFull } from 'maaza/cloud';

const response = await maazaFull(text, schema);
console.log(response);
// → {
//     id: "...",
//     extracted: { ... },
//     validation: { valid: true, errors: [] },
//     usage: { input_tokens: 50, output_tokens: 30 },
//     latency_ms: 387,
//     cached: false,
//     attempts: 1
//   }

Error Handling

try {
  const result = await maaza(text, schema);
} catch (error) {
  if (error.message.includes('quota exceeded')) {
    console.error('Upgrade your plan at https://cyclecore.ai/research');
  } else if (error.message.includes('Invalid API key')) {
    console.error('Get a new API key at https://cyclecore.ai/research');
  } else {
    console.error('Extraction failed:', error);
  }
}

🌐 Platform Support

Cloud mode works everywhere:

• ✅ Node.js (18+)
• ✅ Bun
• ✅ Deno
• ✅ Browser (Chrome 121+)
• ✅ Any JavaScript runtime with fetch

Local mode (ONNX) coming in v1.5.0 for offline use.

📊 Comparison

Maaza vs GPT-4 for JSON Extraction

| Feature | Maaza (Cloud) | GPT-4 Turbo | |---------|---------------|-------------| | Accuracy | 75.7%* | ~90%* | | Latency | 400-800ms | ~1-3s | | Cost (10K req) | $79 | ~$100-300** | | Offline mode | ✅ Yes (v1.5.0) | ❌ No | | Edge deployment | ✅ Yes | ❌ No |

*On EdgeJSON v3 benchmark
**Estimated based on typical token counts

When to use Maaza:

• High-volume extraction (invoices, receipts, forms)
• Cost-sensitive applications
• Edge/offline deployment needed
• Privacy-first architecture

When to use GPT-4:

• Complex reasoning required
• Highest accuracy critical
• Multi-step workflows

🔐 Security & Privacy

Local Mode (Coming v1.5.0):

• ✅ Maaza-360M v1.0 model via ONNX runtime
• ✅ Runs 100% on your machine
• ✅ No data sent anywhere
• ✅ No API key needed
• ✅ Works offline

Cloud Mode:

• ✅ HTTPS encrypted
• ✅ API key authentication
• ✅ Data not used for training
• ✅ Processed and discarded immediately

📚 Examples

Node.js

const { maaza } = require('maaza/cloud');

async function extractInvoice(text) {
  return await maaza(text, {
    invoice_number: "string",
    total: "number",
    date: "string"
  });
}

TypeScript

import { maaza, MaazaResult } from 'maaza/cloud';

async function processReceipt(text: string): Promise<Receipt> {
  const result = await maaza(text, {
    store: "string",
    items: "string",
    total: "number"
  });
  
  return result as Receipt;
}

Deno

import { maaza } from "npm:maaza/cloud";

const result = await maaza(
  Deno.readTextFileSync("invoice.txt"),
  { invoice_id: "string", amount: "number" }
);

🛠️ Development

Requirements

• Node.js 18+
• TypeScript 5+

Build

npm install
npm run build

Test

npm test

📄 License

MIT License - see LICENSE file.

Models are Apache 2.0 - see HuggingFace.

🔗 Links

• Website: cyclecore.ai
• API Docs: cyclecore.ai/research
• Models: HuggingFace
• Support: [email protected]

🌟 Why Maaza?

Built by CycleCore Technologies for indie developers who need:

• ✅ Fast extraction (400-800ms cloud, local coming soon)
• ✅ Accurate results (75.7% on real-world benchmarks)
• ✅ Affordable pricing (30x cheaper than GPT-4 for high-volume)*
• ✅ Privacy-first (local mode = your data never leaves your machine)
• ✅ Edge-ready (small models = deploy anywhere)

*Based on typical extraction workloads and public API pricing as of Nov 2025.

Get started: cyclecore.ai/research

Questions? Open an issue or email [email protected]