melaka 0.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "melaka",
+  "version": "0.0.0",
+  "description": "AI-powered localization for Firebase Firestore",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rizahassan/melaka.git"
+  },
+  "author": "Riza Hassan <vehan.apps@gmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "firebase",
+    "firestore",
+    "i18n",
+    "localization",
+    "translation",
+    "ai",
+    "gemini",
+    "openai",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "packageManager": "pnpm@8.15.0",
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "test": "turbo run test",
+    "test:watch": "turbo run test:watch",
+    "lint": "turbo run lint",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "typecheck": "turbo run typecheck",
+    "clean": "turbo run clean && rm -rf node_modules",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "turbo run build && changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "prettier": "^3.2.0",
+    "turbo": "^2.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  }
+}

package/packages/ai/README.md

@@ -0,0 +1,43 @@
+# @melaka/ai
+
+AI provider adapters for Melaka - AI-powered Firestore localization.
+
+## Installation
+
+```bash
+pnpm add @melaka/ai
+```
+
+## Usage
+
+```typescript
+import { createTranslationFacade } from '@melaka/ai';
+import { z } from 'zod';
+
+const facade = createTranslationFacade({
+  provider: 'gemini',
+  model: 'gemini-2.5-flash',
+  apiKey: process.env.GEMINI_API_KEY,
+});
+
+const result = await facade.translate(
+  { title: 'Hello World', body: 'Welcome to our app' },
+  z.object({ title: z.string(), body: z.string() }),
+  { targetLanguage: 'ms-MY' }
+);
+
+if (result.success) {
+  console.log(result.output);
+  // { title: 'Hello Dunia', body: 'Selamat datang ke aplikasi kami' }
+}
+```
+
+## Supported Providers
+
+- **Gemini** (Google) - `gemini-2.5-flash`, `gemini-2.5-pro`
+- **OpenAI** - `gpt-4o`, `gpt-4o-mini` (Phase 2)
+- **Claude** (Anthropic) - `claude-sonnet-4-20250514` (Phase 2)
+
+## Documentation
+
+See the [main Melaka documentation](https://github.com/rizahassan/melaka).

package/packages/ai/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@melaka/ai",
+  "version": "0.0.0",
+  "description": "AI provider adapters for Melaka",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@melaka/core": "workspace:*",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rizahassan/melaka.git",
+    "directory": "packages/ai"
+  },
+  "license": "MIT"
+}

package/packages/ai/src/facade.ts

@@ -0,0 +1,120 @@
+/**
+ * Melaka AI - Translation Facade
+ *
+ * High-level API for translating content using any configured AI provider.
+ */
+
+import type { z } from 'zod';
+import type { AIConfig } from '@melaka/core';
+import type { AIProvider, ProviderConfig, TranslationOptions, TranslationResponse } from './types';
+import { GeminiProvider } from './providers/gemini';
+
+/**
+ * Translation facade for unified AI provider access.
+ *
+ * @example
+ * ```typescript
+ * const facade = createTranslationFacade({
+ *   provider: 'gemini',
+ *   model: 'gemini-2.5-flash',
+ *   apiKey: process.env.GEMINI_API_KEY,
+ * });
+ *
+ * const result = await facade.translate(
+ *   { title: 'Hello', body: 'Welcome' },
+ *   z.object({ title: z.string(), body: z.string() }),
+ *   { targetLanguage: 'ms-MY' }
+ * );
+ * ```
+ */
+export class TranslationFacade {
+  private provider: AIProvider;
+
+  constructor(aiConfig: AIConfig) {
+    this.provider = createProvider(aiConfig);
+  }
+
+  /**
+   * Translate content using the configured AI provider.
+   *
+   * @param content - Content to translate (translatable fields only)
+   * @param schema - Zod schema defining expected output structure
+   * @param options - Translation options
+   * @returns Translation result
+   */
+  async translate<T>(
+    content: Record<string, unknown>,
+    schema: z.ZodSchema<T>,
+    options: TranslationOptions
+  ): Promise<TranslationResponse<T>> {
+    return this.provider.translate(content, schema, options);
+  }
+
+  /**
+   * Get the underlying AI provider.
+   */
+  getProvider(): AIProvider {
+    return this.provider;
+  }
+
+  /**
+   * Get the provider name.
+   */
+  getProviderName(): string {
+    return this.provider.name;
+  }
+
+  /**
+   * Get the model being used.
+   */
+  getModel(): string {
+    return this.provider.getModel();
+  }
+
+  /**
+   * Check if the facade is properly configured.
+   */
+  isConfigured(): boolean {
+    return this.provider.isConfigured();
+  }
+}
+
+/**
+ * Create an AI provider based on configuration.
+ *
+ * @param aiConfig - AI configuration from melaka.config.ts
+ * @returns Configured AI provider
+ */
+function createProvider(aiConfig: AIConfig): AIProvider {
+  const providerConfig: ProviderConfig = {
+    apiKey: aiConfig.apiKey,
+    model: aiConfig.model,
+    temperature: aiConfig.temperature,
+  };
+
+  switch (aiConfig.provider) {
+    case 'gemini':
+      return new GeminiProvider(providerConfig);
+
+    case 'openai':
+      // TODO: Implement OpenAI provider in Phase 2
+      throw new Error('OpenAI provider not yet implemented. Use Gemini for MVP.');
+
+    case 'claude':
+      // TODO: Implement Claude provider in Phase 2
+      throw new Error('Claude provider not yet implemented. Use Gemini for MVP.');
+
+    default:
+      throw new Error(`Unknown AI provider: ${aiConfig.provider}`);
+  }
+}
+
+/**
+ * Create a translation facade instance.
+ *
+ * @param aiConfig - AI configuration
+ * @returns Configured translation facade
+ */
+export function createTranslationFacade(aiConfig: AIConfig): TranslationFacade {
+  return new TranslationFacade(aiConfig);
+}

package/packages/ai/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @melaka/ai
+ *
+ * AI provider adapters for Melaka - AI-powered Firestore localization.
+ *
+ * @packageDocumentation
+ */
+
+// Types
+export type {
+  AIProvider,
+  ProviderConfig,
+  TranslationOptions,
+  TranslationResponse,
+} from './types';
+
+// Providers
+export {
+  GeminiProvider,
+  createGeminiProvider,
+} from './providers';
+
+// Facade
+export {
+  TranslationFacade,
+  createTranslationFacade,
+} from './facade';
+
+// Prompt utilities
+export {
+  buildTranslationPrompt,
+  buildSystemPrompt,
+  extractJsonFromResponse,
+} from './prompt';

package/packages/ai/src/prompt.ts

@@ -0,0 +1,117 @@
+/**
+ * Melaka AI - Prompt Builder
+ *
+ * Constructs prompts for AI translation with context, glossaries, and instructions.
+ */
+
+import { formatGlossary, getLanguageName } from '@melaka/core';
+import type { TranslationOptions } from './types';
+
+/**
+ * Build a translation prompt for the AI provider.
+ *
+ * @param content - Content to translate
+ * @param options - Translation options
+ * @returns Formatted prompt string
+ */
+export function buildTranslationPrompt(
+  content: Record<string, unknown>,
+  options: TranslationOptions
+): string {
+  const { targetLanguage, prompt, glossary } = options;
+  const languageName = getLanguageName(targetLanguage);
+
+  const sections: string[] = [];
+
+  // Main instruction
+  sections.push(`Translate the following content from English to ${languageName} (${targetLanguage}).`);
+
+  // Preservation rules
+  sections.push(`
+Preserve exactly:
+- JSON structure and field names
+- Markdown formatting (headers, bold, italic, links, code blocks)
+- Proper nouns (names, brands, places) unless glossary specifies otherwise
+- Numbers, dates, and measurements
+- URLs, email addresses, and code snippets
+- Emoji and special characters`);
+
+  // Custom context
+  if (prompt) {
+    sections.push(`
+Context:
+${prompt}`);
+  }
+
+  // Glossary
+  sections.push(`
+Glossary (use these translations consistently):
+${formatGlossary(glossary)}`);
+
+  // Content to translate
+  sections.push(`
+Content to translate:
+${JSON.stringify(content, null, 2)}`);
+
+  // Output instruction
+  sections.push(`
+Respond with ONLY the translated JSON object. Do not include any explanation or markdown code blocks.`);
+
+  return sections.join('\n');
+}
+
+/**
+ * Build a system prompt for translation tasks.
+ *
+ * @returns System prompt string
+ */
+export function buildSystemPrompt(): string {
+  return `You are a professional translator specializing in software localization.
+
+Your task is to translate content while:
+1. Maintaining the exact JSON structure
+2. Preserving technical terms, brand names, and proper nouns
+3. Adapting idioms and cultural references appropriately
+4. Ensuring natural, fluent translations in the target language
+5. Following any glossary terms provided exactly
+
+Always respond with valid JSON that matches the input structure.`;
+}
+
+/**
+ * Extract JSON from AI response that may contain markdown or extra text.
+ *
+ * @param response - Raw AI response
+ * @returns Parsed JSON object
+ * @throws Error if no valid JSON found
+ */
+export function extractJsonFromResponse(response: string): Record<string, unknown> {
+  // Try direct parse first
+  try {
+    return JSON.parse(response);
+  } catch {
+    // Continue to extraction
+  }
+
+  // Try to extract from markdown code block
+  const codeBlockMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (codeBlockMatch) {
+    try {
+      return JSON.parse(codeBlockMatch[1].trim());
+    } catch {
+      // Continue to other methods
+    }
+  }
+
+  // Try to find JSON object in the response
+  const jsonMatch = response.match(/\{[\s\S]*\}/);
+  if (jsonMatch) {
+    try {
+      return JSON.parse(jsonMatch[0]);
+    } catch {
+      // Fall through to error
+    }
+  }
+
+  throw new Error('Failed to extract valid JSON from AI response');
+}

package/packages/ai/src/providers/gemini.ts

@@ -0,0 +1,185 @@
+/**
+ * Melaka AI - Gemini Provider
+ *
+ * AI provider adapter for Google's Gemini models.
+ * Uses direct Gemini API for MVP (Genkit integration in Phase 2).
+ */
+
+import type { z } from 'zod';
+import type { AIProvider, ProviderConfig, TranslationOptions, TranslationResponse } from '../types';
+import { buildTranslationPrompt, buildSystemPrompt, extractJsonFromResponse } from '../prompt';
+
+/**
+ * Gemini API response structure.
+ */
+interface GeminiResponse {
+  candidates?: Array<{
+    content?: {
+      parts?: Array<{
+        text?: string;
+      }>;
+    };
+  }>;
+  usageMetadata?: {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    totalTokenCount?: number;
+  };
+}
+
+/**
+ * Gemini AI provider.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiProvider({
+ *   apiKey: process.env.GEMINI_API_KEY,
+ *   model: 'gemini-2.5-flash',
+ * });
+ *
+ * const result = await provider.translate(
+ *   { title: 'Hello' },
+ *   z.object({ title: z.string() }),
+ *   { targetLanguage: 'ms-MY' }
+ * );
+ * ```
+ */
+export class GeminiProvider implements AIProvider {
+  readonly name = 'gemini';
+
+  private config: ProviderConfig;
+
+  constructor(config: ProviderConfig) {
+    this.config = {
+      temperature: 0.3,
+      ...config,
+    };
+  }
+
+  async translate<T>(
+    content: Record<string, unknown>,
+    schema: z.ZodSchema<T>,
+    options: TranslationOptions
+  ): Promise<TranslationResponse<T>> {
+    const startTime = Date.now();
+
+    try {
+      if (!this.isConfigured()) {
+        return {
+          success: false,
+          error: 'Gemini API key not configured',
+        };
+      }
+
+      // Build the prompt
+      const userPrompt = buildTranslationPrompt(content, {
+        ...options,
+        temperature: options.temperature ?? this.config.temperature,
+      });
+
+      const systemPrompt = buildSystemPrompt();
+
+      // Call Gemini API directly
+      const response = await fetch(
+        `https://generativelanguage.googleapis.com/v1beta/models/${this.config.model}:generateContent?key=${this.config.apiKey}`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            contents: [
+              {
+                parts: [{ text: userPrompt }],
+              },
+            ],
+            systemInstruction: {
+              parts: [{ text: systemPrompt }],
+            },
+            generationConfig: {
+              temperature: options.temperature ?? this.config.temperature,
+              responseMimeType: 'application/json',
+            },
+          }),
+        }
+      );
+
+      const durationMs = Date.now() - startTime;
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        return {
+          success: false,
+          error: `Gemini API error: ${response.status} ${JSON.stringify(errorData)}`,
+          durationMs,
+        };
+      }
+
+      const data = await response.json() as GeminiResponse;
+
+      // Extract text from response
+      const textResponse = data.candidates?.[0]?.content?.parts?.[0]?.text;
+
+      if (!textResponse) {
+        return {
+          success: false,
+          error: 'No response from Gemini',
+          durationMs,
+        };
+      }
+
+      // Parse and validate
+      const parsed = extractJsonFromResponse(textResponse);
+      const validated = schema.safeParse(parsed);
+
+      if (!validated.success) {
+        return {
+          success: false,
+          error: `Schema validation failed: ${validated.error.message}`,
+          durationMs,
+        };
+      }
+
+      // Extract usage metadata
+      const usageMetadata = data.usageMetadata;
+
+      return {
+        success: true,
+        output: validated.data,
+        usage: usageMetadata
+          ? {
+              inputTokens: usageMetadata.promptTokenCount || 0,
+              outputTokens: usageMetadata.candidatesTokenCount || 0,
+              totalTokens: usageMetadata.totalTokenCount || 0,
+            }
+          : undefined,
+        durationMs,
+      };
+    } catch (error) {
+      const durationMs = Date.now() - startTime;
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        durationMs,
+      };
+    }
+  }
+
+  isConfigured(): boolean {
+    return !!this.config.apiKey;
+  }
+
+  getModel(): string {
+    return this.config.model;
+  }
+}
+
+/**
+ * Create a Gemini provider instance.
+ *
+ * @param config - Provider configuration
+ * @returns Configured Gemini provider
+ */
+export function createGeminiProvider(config: ProviderConfig): GeminiProvider {
+  return new GeminiProvider(config);
+}

package/packages/ai/src/providers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Melaka AI - Provider Exports
+ */
+
+export { GeminiProvider, createGeminiProvider } from './gemini';
+
+// Future providers:
+// export { OpenAIProvider, createOpenAIProvider } from './openai';
+// export { ClaudeProvider, createClaudeProvider } from './claude';