Schema.ICU SDK

Production-ready Node.js SDK for Schema.ICU - Structured AI with cryptographic verification

Features

• 🎯 11 Specialized AI Agents - Code generation, schema design, project planning, and more
• 🔐 Cryptographic Verification - Every response is signed with BSV cryptography
• 🛡️ Post-Quantum Ready - ML-DSA-65/87 quantum-resistant signatures (NIST FIPS 204)
• ✅ JSON Schema Validation - Guaranteed structured outputs
• 🚀 Production Ready - Error handling, rate limiting, 99.9% uptime SLA
• ⚡ Cost Optimized - GPT-5-nano at $0.05/1M tokens (96% cheaper than GPT-4)
• 🛠️ Interactive CLI - Setup wizard and command-line tools
• 📦 TypeScript Ready - Full type definitions (coming soon)

Installation

npm install @smartledger/schema-icu-sdk

Quick Start

1. Setup

Run the interactive setup wizard:

npm run setup

Or use the CLI:

npx schema-icu setup

This will guide you through:

• Creating an account or logging in
• Configuring your API credentials
• Saving configuration to .env

2. Basic Usage

const { SchemaICU } = require('@smartledger/schema-icu-sdk');

// Initialize client (loads credentials from .env)
const client = new SchemaICU();

// Generate code
const result = await client.codeGenerator.generate(
  'Create a debounce function in JavaScript',
  { language: 'JavaScript', style: 'modern ES6+' }
);

console.log(result.code);
console.log('Complexity:', result.complexity);
console.log('Reasoning:', result.reasoning);

Available Agents

| Agent | Endpoint | Description | |-------|----------|-------------| | Base Agent | client.base | General-purpose with code generation | | Code Generator | client.codeGenerator | Production-ready code in any language | | Schema Generator | client.schemaGenerator | JSON schemas with validation rules | | Terminal Agent | client.terminalAgent | Optimal shell commands | | Code Improver | client.codeImprover | Optimize without breaking changes | | Diff Improver | client.diffImprover | Improvements with unified diffs | | Box Designer | client.boxDesigner | Modular components (Alan Kay) | | Project Planner | client.projectPlanner | Task breakdown with time estimates | | Prompt Improver | client.promptImprover | Optimize prompts for better results | | Tool Choice | client.toolChoice | Best agent recommendation | | GitHub Agent | client.githubAgent | GitHub CLI commands |

Examples

Code Generation

const { SchemaICU } = require('@smartledger/schema-icu-sdk');
const client = new SchemaICU();

const result = await client.codeGenerator.generate(
  'Create a REST API endpoint for user registration',
  {
    language: 'JavaScript',
    framework: 'Express',
    features: ['validation', 'error handling']
  }
);

console.log(result.code);
console.log('Complexity:', result.complexity);
console.log('Reasoning:', result.reasoning);

Code Improvement

const code = `
function getData(id) {
  var result;
  if (id) {
    result = database.get(id);
  }
  return result;
}
`;

const result = await client.diffImprover.improve(code, {
  language: 'JavaScript',
  focusAreas: ['performance', 'security', 'readability']
});

console.log('Improved:', result.improvedCode);
console.log('Diff:', result.diff);
console.log('Explanation:', result.explanation);

Project Planning

const result = await client.projectPlanner.plan(
  'Build a chat application with real-time messaging',
  {
    technology: 'Node.js, React, WebSocket',
    experience: 'intermediate'
  }
);

console.log(`Project: ${result.projectName}`);
console.log(`Tasks: ${result.tasks.length}`);

result.tasks.forEach(task => {
  console.log(`- ${task.taskName} (${task.estimatedTimeHours}h)`);
});

Schema Generation

const result = await client.schemaGenerator.generate(
  'Create a schema for a product catalog with categories'
);

const schema = JSON.parse(result.schemaAsString);
console.log(schema);

Authentication

Login Programmatically

const { SchemaICU } = require('@smartledger/schema-icu-sdk');
const client = new SchemaICU();

const loginResult = await client.auth.login('[email protected]', 'password');

if (loginResult.success) {
  console.log('API Key:', loginResult.user.apiKey);
  console.log('Token:', loginResult.token);
  
  // Update config
  client.config.apiKey = loginResult.user.apiKey;
  client.config.jwtToken = loginResult.token;
}

Register New Account

// Register
const registerResult = await client.auth.register(
  '[email protected]',
  'securePassword123'
);

// Verify email with OTP
const verifyResult = await client.auth.verifyEmail(
  '[email protected]',
  '123456'
);

console.log('API Key:', verifyResult.apiKey);

Configuration

Environment Variables

Create a .env file:

SCHEMA_ICU_API_KEY=your_api_key_here
SCHEMA_ICU_JWT_TOKEN=your_jwt_token_here
[email protected]
SCHEMA_ICU_BASE_URL=schema.icu
SCHEMA_ICU_PORT=443

Programmatic Configuration

const { SchemaICU, Config } = require('@smartledger/schema-icu-sdk');

const config = new Config({
  apiKey: 'your_api_key',
  jwtToken: 'your_jwt_token',
  timeout: 30000,
  retryAttempts: 3
});

const client = new SchemaICU(config);

CLI Commands

# Setup wizard
npm run setup

# Run examples
npm run example:basic
npm run example:improve
npm run example:plan

# Improve a file
npx schema-icu improve server.js

# Generate code
npx schema-icu generate "Create a REST API"

Error Handling

const { 
  SchemaICU,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  APIError 
} = require('@smartledger/schema-icu-sdk');

const client = new SchemaICU();

try {
  const result = await client.codeGenerator.generate('...');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else {
    console.error('API error:', error.message);
  }
}

Post-Quantum Cryptography

Schema.ICU supports quantum-resistant cryptographic signatures using ML-DSA (Module-Lattice-Based Digital Signature Algorithm) based on NIST FIPS 204.

Why Post-Quantum?

Current ECDSA signatures will be vulnerable when practical quantum computers emerge (~10-20 years). ML-DSA signatures are quantum-resistant today, ensuring your cryptographic proofs remain valid in the post-quantum era.

Available Algorithms

| Algorithm | Security Level | Signature Size | Use Case | |-----------|---------------|----------------|----------| | ECDSA (default) | Classical | ~88 chars | Standard use, smallest size | | ml-dsa-65 | NIST Level 3 | ~4,412 chars (50x) | Recommended for most PQ needs | | ml-dsa-87 | NIST Level 5 | ~6,172 chars (70x) | Maximum security, high-value ops | | pq (alias) | NIST Level 5 | ~6,172 chars (70x) | Shorthand for ml-dsa-87 |

Usage Methods

Method 1: Pass in Context

const result = await client.codeGenerator.generate(
  'Create a secure authentication function',
  {
    signatureAlgorithm: 'ml-dsa-65',
    language: 'JavaScript'
  }
);

console.log('Algorithm:', result.signature.algorithm);        // 'ml-dsa-65'
console.log('Quantum-resistant:', result.signature.quantumResistant); // true
console.log('Signature length:', result.signature.signature.length);   // ~4412

Method 2: Client Helper Methods

// Set post-quantum for all subsequent requests
client.usePostQuantum('ml-dsa-87');
console.log(client.getSignatureAlgorithm()); // 'ml-dsa-87'

const result = await client.codeGenerator.generate('...');
// Will use ML-DSA-87 signature

// Switch back to ECDSA
client.useECDSA();
console.log(client.getSignatureAlgorithm()); // 'ecdsa'

Method 3: Use PQ Alias

// 'pq' is a convenient shorthand for 'ml-dsa-87'
const result = await client.schemaGenerator.generate(
  'Create a user schema',
  { signatureAlgorithm: 'pq' }
);

console.log(result.signature.algorithm); // 'ml-dsa-87'

All Agents Support PQ

Post-quantum signatures work with all agents:

// Base Agent
await client.base.query('...', { signatureAlgorithm: 'ml-dsa-65' });

// Code Generator
await client.codeGenerator.generate('...', { signatureAlgorithm: 'ml-dsa-87' });

// Code Improver
await client.codeImprover.improve('...', { signatureAlgorithm: 'pq' });

// Schema Generator
await client.schemaGenerator.generate('...', { signatureAlgorithm: 'ml-dsa-65' });

// Project Planner
await client.projectPlanner.plan('...', { signatureAlgorithm: 'ml-dsa-87' });

// And all other agents...

Enhanced Signature Response

When using post-quantum signatures, the response includes additional metadata:

{
  signature: {
    hash: "992ca02ee975884200cdb5c567eff3dbb9b916b1fd93c758be7dd876213371b1",
    signature: "5nnm5y9SHZTQijl2y2/Arm1dkqzDfmvTAlmbKSPiK3Q3tO...",
    publicKey: "8a4b02f0eafac5d36676e5b68d05667e23a295185cf45a0c04ac04fe7d9bcd89",
    algorithm: "ml-dsa-65",                    // Signature algorithm used
    suite: "ml-dsa-65",                        // Cryptographic suite
    quantumResistant: true,                    // NEW: Indicates quantum resistance
    signedAt: "2025-12-19T05:13:51.125Z"
  }
}

Best Practices

1. Default to ML-DSA-65 for most production use cases - good balance of security and size
2. Use ML-DSA-87 for high-value operations requiring maximum security
3. Use PQ alias for convenience when you want the strongest protection
4. Consider signature size - PQ signatures are 50-70x larger than ECDSA
5. Test performance - PQ signatures may take slightly longer to generate

Complete Example

See examples/post-quantum-signatures.js for a comprehensive demonstration.

// Quick comparison of all algorithms
const results = {
  ecdsa: await client.base.query('test'),
  mldsa65: await client.base.query('test', { signatureAlgorithm: 'ml-dsa-65' }),
  mldsa87: await client.base.query('test', { signatureAlgorithm: 'ml-dsa-87' })
};

console.log('ECDSA:', results.ecdsa.signature.signature.length, 'chars');
console.log('ML-DSA-65:', results.mldsa65.signature.signature.length, 'chars (quantum-safe)');
console.log('ML-DSA-87:', results.mldsa87.signature.signature.length, 'chars (quantum-safe)');

API Reference

SchemaICU Client

const client = new SchemaICU(options);

// Properties
client.auth              // AuthManager
client.base              // BaseAgent
client.codeGenerator     // CodeGenerator
client.schemaGenerator   // SchemaGenerator
client.terminalAgent     // TerminalAgent
client.codeImprover      // CodeImprover
client.diffImprover      // DiffImprover
client.boxDesigner       // BoxDesigner
client.projectPlanner    // ProjectPlanner
client.promptImprover    // PromptImprover
client.toolChoice        // ToolChoice
client.githubAgent       // GitHubAgent

// Methods
client.isAuthenticated()
client.getConfig()
client.updateConfig(options)

// Post-Quantum Helper Methods (v1.0.4+)
client.usePostQuantum(algorithm)      // Set PQ algorithm ('ml-dsa-65', 'ml-dsa-87', 'pq')
client.useECDSA()                     // Switch back to ECDSA (default)
client.getSignatureAlgorithm()        // Get current algorithm
client.setSignatureAlgorithm(algorithm) // Set custom algorithm

Common Response Format

All API responses include:

{
  success: true,
  // Agent-specific data fields at top level
  code: "...",              // For code generator
  improvedCode: "...",      // For code improver
  schemaAsString: "...",    // For schema generator
  projectName: "...",       // For project planner
  tasks: [],                // For project planner
  // Common fields
  timestamp: "2025-12-08T13:52:42.655Z",
  signature: {
    hash: "...",
    signature: "...",
    publicKey: "...",
    algorithm: "ecdsa",
    suite: "bsv-ecdsa-secp256k1",
    signedAt: "2025-12-08T13:52:42.719Z"
  }
}

Note: Response data is at the top level, not nested under a data property.

Pricing

• Free Tier: 21 requests/day
• Registered: 200 requests/day
• Professional: $49/month for 3M requests
• Enterprise: Unlimited requests

View pricing details →

Examples Directory

See the examples/ directory for more:

• basic-usage.js - Simple SDK usage
• code-improvement.js - File improvement workflow
• project-planning.js - Project planning example
• authentication.js - Auth flows

Development

# Install dependencies
npm install

# Run tests
npm test

# Run setup wizard
npm run setup

Contributing

Contributions welcome! Please read our Contributing Guide.

License

MIT © SmartLedger Technologies

Links

• Schema.ICU Website
• API Documentation
• GitHub Repository
• Issue Tracker

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://schema.icu/docs
• 💬 GitHub Issues: https://github.com/codenlighten/schema-icu-sdk/issues

Built with ❤️ by SmartLedger Technologies