@wellysa/algs-engine

AI-powered algorithms engine with configurable parameter parsing, caching, and multi-source data integration.

Tech Stack

• Runtime: Bun 1.1.30+
• Language: TypeScript 5.6+
• AI/LLM: Vercel AI SDK with OpenAI integration
• Data Sources: Airtable, In-Memory
• Caching: Redis (via Docker), cache-manager, LRU cache, Keyv
• Validation: Zod schemas
• Logging: tslog
• Utilities: Luxon (dates), uuid/cuid2 (IDs)

Prerequisites

• Bun v1.1.30 or higher
• Docker & Docker Compose (for Redis caching)
• Airtable API credentials (if using Airtable integration)
• OpenAI API key (for AI features)

Setup & Installation

1. Install dependencies:

   bun install

2. Configure environment:

   cp .env.template .env
   # Edit .env with your API keys and configuration

3. Start infrastructure (Redis):

   bun run docker

   This launches Redis and other required services via Docker Compose.

Running the Application

Development mode (with hot reload):

bun run dev

Production build:

bun run build
bun run start:prod

Type checking only:

bun run typecheck

Architecture Overview

The engine follows a pipeline-based architecture with pluggable integrations:

┌─────────────────┐
│ Data Sources    │  (Airtable / In-Memory)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Raw Loader      │  (src/engine/core/raw-algorithms-loader.ts)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Transformer     │  (src/engine/core/raw-algorithms-transformer.ts)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Analyzer        │  (src/engine/core/analyzer.ts)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Engine Output   │  (src/engine/engine.ts)
└─────────────────┘

Parameter Types

The engine supports multiple parameter parsing strategies:

• Comparison - relational operators (>, <, >=, <=, ==, !=)
• Constant - fixed values
• Enum - predefined options
• Range - min/max boundaries

Caching Strategy

Multi-layer caching with Redis backend and LRU in-memory fallback for performance optimization.

Project Structure

src/
├── ai/                    # AI model creation & configuration
├── engine/
│   ├── core/             # Core engine components (loader, transformer, analyzer)
│   ├── pipelines/        # Data processing pipelines
│   └── utils/            # Matchers & utilities
├── integrations/
│   ├── airtable/         # Airtable data source integration
│   └── in-memory/        # In-memory data source + parsers
├── lib/
│   ├── cache/            # Caching layer implementation
│   └── logger/           # Logging adapters
├── common/
│   ├── schemas/          # Zod validation schemas (algorithm, parameter)
│   ├── constants/        # Global constants, operators, regex patterns
│   └── exceptions/       # Custom exception classes
└── main.ts               # Application entry point

config/
└── input.json            # Algorithm input configuration

.docker/
└── services/redis/       # Redis Docker setup

Development

Git Hooks

The project uses Husky for automated checks:

• commit-msg - Conventional Commits validation
• post-merge - Lock file change notifications
• pre-push - Lock file validation

Code Quality

• Linting: ESLint with Prettier integration
• Formatting: Prettier with auto-sorted imports
• Type Safety: Strict TypeScript configuration

Scripts

• bun run check-lock-files - Validate lock file integrity
• bun run clean - Remove build artifacts
• bun run build - Compile TypeScript to dist/

Configuration

Algorithm definitions are loaded from:

1. config/input.json - Local configuration file
2. Airtable base (requires API credentials in .env)

Schema validation is enforced via Zod schemas in src/common/schemas/.

---

Note: Business logic details, specific algorithm use cases, and API endpoints require domain knowledge confirmation. (unverified — confirm with team)