Package Exports

@cellular-ai/engine

Readme

@cellular-ai/engine

API for building agentic coding editors/platforms | NPM

Features

AI-powered code generation with streaming support
Tool execution with automatic function calling
Memory management for context-aware conversations
Express.js integration for easy web server setup
TypeScript support with full type definitions

Installation

npm install @cellular-ai/engine

Quick Start

Basic Usage

import { engine, stream } from '@cellular-ai/engine';

// Create an engine instance
const engineInstance = engine({
  dir: '/path/to/project',
  fullContext: true,
  sessionId: 'session-123',
  apikey: 'your-api-key',
  debug: false
});

// Stream AI responses
for await (const token of engineInstance.stream('Write a function to sort an array')) {
  process.stdout.write(token);
}

Express.js Integration

import express from 'express';
import { stream } from '@cellular-ai/engine';

const app = express();

app.post('/generate', async (req, res) => {
  const { prompt, dir, context } = req.body;
  const setHeaders = true;

  // Create engine for specific request
  const engineInstance = engine({
    dir: dir,
    fullContext: true,
    sessionId: 'session-123',
    apikey: 'your-api-key',
    debug: false
  });
  
  // Stream agent response w/ tool calls for given prompt
  await stream(res, engineInstance, prompt, setHeaders, context);
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

The stream function returns data in standard SSE format:

Content events: data: {"type": "text", "content": "hello world", "timestamp": "..."}

Tool events:

event: tool_request
data: {"type": "tool_request", "content": {...}, "timestamp": "..."}

API Reference

`engine(config)`

Creates a new engine instance.

Parameters:

config (EngineConfig): Configuration object with the following properties:
- dir (string): Project directory path
- fullContext (boolean, optional): Whether to dump entire codebase into context window. Default: false
- model (string, optional): Model to use. Options: 'pro', 'flash', 'mini'. Default: 'flash'
- apikey (string, optional): Gemini API key. Can also be set via GEMINI_API_KEY environment variable.
- sessionId (string, optional): Session identifier. Auto-generated if not provided.
- debug (boolean): Enable debug logging

Returns: EngineService instance

`stream(response, engine, prompt, setHeaders?, context?)`

Express Integration to Streams AI responses seamlessly.

Parameters:

response (Response): Express.js response object.
engine (EngineService): Engine instance.
prompt (string): User prompt.
setHeaders (boolean, optional): Whether to set required SSE headers automatically. Default: false
context (string, optional): Additional context.

EngineService Methods

`stream(message, context?)`

Streams AI responses as an async generator. Ideal for ask type questions that do not require tool usage.

for await (const token of engineInstance.stream('Your prompt here')) {
  console.log(token);
}

`streamWithToolEvents(message, context?)`

Streams AI responses with tool execution events as an async generator. Ideal for project-wide agent queries.

for await (const event of engineInstance.streamWithToolEvents('Your prompt here')) {
  if (event.type === 'text') {
    console.log(event.data);
  } else if (event.type === 'tool_request') {
    console.log('Tool requested:', event.data);
  }
}

`getTools()`

Returns available tools as function declarations.

const tools = await engineInstance.getTools();
console.log('Available tools:', tools.map(t => t.name));

`executeTool(toolName, params)`

Executes a specific tool with parameters.

const result = await engineInstance.executeTool('read-file', { path: './example.js' });
console.log(result);

`getMemoryContent()`

Returns the current memory content.

const memory = engineInstance.getMemoryContent();
console.log('Memory content:', memory);

Configuration

Environment Variables

GEMINI_API_KEY: Your Gemini API key (required)

Examples

Code Generation

import { engine } from '@cellular-ai/engine';

const engineInstance = engine({
  dir: './my-project',
  fullContext: true,
  sessionId: 'code-gen-session',
  debug: false
});

for await (const token of engineInstance.stream(
  'Create a React component that displays a user profile'
)) {
  process.stdout.write(token);
}

Streaming with Tool Events

import { engine } from '@cellular-ai/engine';

const engineInstance = engine({
  dir: './my-project',
  fullContext: true,
  sessionId: 'code-gen-session',
  debug: false
});

for await (const event of engineInstance.streamWithToolEvents(
  'Create a React component that displays a user profile'
)) {
  switch (event.type) {
    case 'text':
      process.stdout.write(event.data);
      break;
    case 'tool_request':
      console.log('🛠️ Tool requested:', event.data.name);
      break;
    case 'tool_start':
      console.log('🚀 Tool started:', event.data.name);
      break;
    case 'tool_result':
      console.log('✅ Tool completed:', event.data.name);
      break;
    case 'tool_error':
      console.log('❌ Tool failed:', event.data.name);
      break;
  }
}

Tool Execution

import { engine } from '@cellular-ai/engine';

const engineInstance = engine({
  dir: './my-project',
  debug: false
});

// Get available tools
const tools = await engineInstance.getTools();
console.log('Available tools:', tools.map(t => t.name));

// Execute a specific tool
const fileContent = await engineInstance.executeTool('read-file', {
  path: './src/index.js'
});
console.log('File content:', fileContent);

License

All code in this project is maintained under the Apache-2.0 License