Skip to main content
Version: 2.6

Core Libraries

The Operaide framework provides a comprehensive set of core libraries that form the foundation for building powerful AI-powered workflows. These libraries offer type-safe, composable components that handle everything from basic data operations to advanced AI integrations.

Library Overview​

@operaide/aktor​

The foundational library providing the core Aktor interface and basic building blocks for creating reactive, composable workflows.

@operaide/ai​

Advanced AI integration library with support for multiple LLM providers, streaming responses, and intelligent prompt management.

@operaide/database​

Database connectivity and operations library supporting SQL and NoSQL databases with type-safe query builders.

@operaide/documents​

Document processing and knowledge management library with vector search, text extraction, and content analysis capabilities.

@operaide/mail​

Email processing and sending library with template support, attachment handling, and multi-provider integration.

Architecture Principles​

Type Safety​

All core libraries are built with TypeScript and provide full type inference throughout your workflows:

// Type is automatically inferred as Aktor<number>
const result = createAktorFunction('aktorAdd', {
    x: aktorConst(5),
    y: aktorConst(10)
});

Composability​

Libraries are designed to work seamlessly together:

import { aktorAICall } from '@operaide/ai';
import { aktorQuery } from '@operaide/database';
import { aktorCompletePrompt } from '@operaide/ai';

const intelligentQuery = aktorAICall({
    messages: aktorMessagesFromSystemAndUser({
        user: aktorCompletePrompt({
            template: aktorConst('Analyze this data: {{data}}'),
            data: aktorQuery({
              client: dbWithInsertedData,
              schema: userSchema,
              sql: aktorConst('SELECT * FROM users LIMIT 10')
            })
        })
    }),
    providerModel: aktorAISettingProviderModel()
});

Lazy Evaluation​

All Aktors use lazy evaluation - they only execute when their values are needed:

const expensiveOperation = aktorAICall({
    messages: complexPrompt,
    providerModel: aktorAISettingProviderModel()
});

// The AI call only happens when we actually need the result
const result = await expensiveOperation.get();

Caching​

Results are automatically cached until dependencies change:

const cachedResult = createAktorFunction('aktorProcessData', { input: data });

// First call executes the function
const value1 = await cachedResult.get();

// Second call returns cached result (if input hasn't changed)
const value2 = await cachedResult.get();

Library Versioning​

All core libraries follow semantic versioning:

  • Major versions (1.0.0 → 2.0.0): Breaking changes
  • Minor versions (1.0.0 → 1.1.0): New features, backward compatible
  • Patch versions (1.0.0 → 1.0.1): Bug fixes, backward compatible

Registry Access​

View the latest versions and documentation at the Operaide Registry.

Backward Compatibility​

We maintain backward compatibility within major versions. When breaking changes are necessary:

  1. Deprecation warnings are issued in advance
  2. Migration guides are provided
  3. Automated migration tools are available when possible

Best Practices​

1. Import Only What You Need​

// Good: Specific imports
import { aktorAICall, aktorCompletePrompt } from '@operaide/ai';

// Avoid: Wildcard imports (affects bundle size)
import * as AI from '@operaide/ai';

2. Use Type Definitions​

import { Aktor } from '@operaide/aktor';
import { z } from 'zod';

// Define clear interfaces for complex data
const UserSchema = z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email()
});

type User = z.infer<typeof UserSchema>;

3. Use Settings for Configuration​

import { aktorSetting } from '@operaide/aktor';
import { z } from 'zod';

const apiEndpoint = aktorSetting(
    z.string().url().describe('API endpoint URL'),
    'https://api.example.com/v1'
);

const timeout = aktorSetting(
    z.number().min(1000).describe('Request timeout in milliseconds'),
    5000
);

IntelliSense and IDE Support​

All core libraries provide excellent IDE support:

  • Auto-completion: Full IntelliSense for all functions and types
  • Type checking: Real-time TypeScript error detection
  • Documentation: Hover documentation for all APIs
  • Navigation: Go-to-definition for easy code exploration

VS Code Extensions​

Recommended extensions for optimal development experience:

  • TypeScript and JavaScript Language Features (built-in)
  • Auto Import - ES6, TS, JSX, TSX

Community and Support​

Getting Help​

  • Documentation: Comprehensive guides and API reference
  • Examples: Working examples in the /examples directory

What's Next?​

Explore each library in detail:

Or jump into the Examples to see these libraries in action!