@almadar/agent 2.0.5 → 3.1.0

package/dist/memory/local-memory-backend.d.ts

@@ -47,9 +47,9 @@ export declare class LocalMemoryBackend {
     getAllErrorResolutions(): Promise<ErrorResolution[]>;
     getUserPreferences(_userId: string): Promise<UserPreference | null>;
     updateUserPreferences(_userId: string, _preferences: Partial<Omit<UserPreference, 'id' | 'userId' | 'learnedAt'>>): Promise<void>;
-    recordGeneration(_userId: string, _session: Omit<GenerationSession, 'id' | 'userId' | 'createdAt'>): Promise<string>;
-    getGenerationSession(_sessionId: string): Promise<GenerationSession | null>;
-    getUserGenerationHistory(_userId: string, _limit?: number): Promise<GenerationSession[]>;
+    recordGeneration(_userId: string, session: Omit<GenerationSession, 'id' | 'userId' | 'createdAt'>): Promise<string>;
+    getGenerationSession(sessionId: string): Promise<GenerationSession | null>;
+    getUserGenerationHistory(_userId: string, limit?: number): Promise<GenerationSession[]>;
     getProjectContext(_appId: string): Promise<ProjectContext | null>;
     updateProjectContext(_appId: string, _update: Partial<Omit<ProjectContext, 'id' | 'appId'>>): Promise<void>;
     updatePatternAffinity(_userId: string, _patternId: string, _outcome: 'success' | 'failure' | 'partial', _context?: {

package/dist/neural/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Neural Pipeline Module
+ *
+ * Schema generation via the Masar server. The neural pipeline (GFlowNet +
+ * LLM fix loop) now runs server-side in the Masar container. This module
+ * provides the HTTP client and shared types.
+ *
+ * @packageDocumentation
+ */
+export type { GoalSpec, NeuralGenerateResult, NeuralPipelineResult, NeuralPipelineOptions, CommandExecutor, PythonExecutor, InferOptions, InferResult, ValidationError, ValidationResult, CompileResult, } from './types.js';
+export { MasarClient } from './masar-client.js';
+export type { MasarClientOptions } from './masar-client.js';

package/dist/neural/index.js

@@ -0,0 +1,86 @@
+// src/neural/masar-client.ts
+var MasarClient = class {
+  constructor(options) {
+    this.baseUrl = (options?.baseUrl ?? process.env["MASAR_URL"] ?? "https://masar-345008351456.europe-west4.run.app").replace(/\/$/, "");
+    this.timeoutMs = options?.timeoutMs ?? 12e4;
+    this.onProgress = options?.onProgress ?? null;
+  }
+  /**
+   * Generate an .orb schema from a natural language prompt.
+   *
+   * Sends the prompt to the Masar server which runs the full neural pipeline
+   * (goal parsing, GFlowNet generation, validation, LLM fix loop) and returns
+   * the result.
+   */
+  async generate(prompt) {
+    this.onProgress?.("request", `Sending prompt to Masar at ${this.baseUrl}`);
+    const url = `${this.baseUrl}/generate`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ prompt }),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        return makeErrorResult(
+          `Masar server returned ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`
+        );
+      }
+      const data = await response.json();
+      this.onProgress?.("response", data.success ? "Generation succeeded" : `Generation failed: ${data.error ?? "unknown"}`);
+      return toNeuralPipelineResult(data);
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        return makeErrorResult(`Masar request timed out after ${this.timeoutMs}ms`);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return makeErrorResult(`Masar request failed: ${message}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+function toNeuralPipelineResult(data) {
+  return {
+    success: data.success,
+    validationPass: data.validation_pass,
+    compilationPass: false,
+    goalMatch: data.goal_match ?? 0,
+    totalSteps: data.total_steps ?? 0,
+    fixRounds: data.fix_rounds ?? 0,
+    llmCalls: data.llm_calls ?? 0,
+    durationMs: data.duration_ms ?? 0,
+    schema: data.schema ?? null,
+    schemaPath: null,
+    actions: data.actions ?? [],
+    validationErrors: data.validation_errors ?? [],
+    compilationErrors: [],
+    error: data.error ?? null
+  };
+}
+function makeErrorResult(error) {
+  return {
+    success: false,
+    validationPass: false,
+    compilationPass: false,
+    goalMatch: 0,
+    totalSteps: 0,
+    fixRounds: 0,
+    llmCalls: 0,
+    durationMs: 0,
+    schema: null,
+    schemaPath: null,
+    actions: [],
+    validationErrors: [],
+    compilationErrors: [],
+    error
+  };
+}
+
+export { MasarClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/neural/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/neural/masar-client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Masar HTTP Client\n *\n * Calls the Masar server's /generate endpoint via HTTP instead of\n * orchestrating the neural pipeline (GFlowNet + LLM fix loop) directly.\n *\n * The Masar server runs the full pipeline server-side and returns\n * a NeuralPipelineResult-compatible response.\n */\n\nimport type { NeuralPipelineResult } from './types.js';\n\n/** Response shape returned by the Masar /generate endpoint (snake_case from Python). */\ninterface MasarGenerateResponse {\n  success: boolean;\n  schema: string | null;\n  validation_pass: boolean;\n  goal_match: number;\n  total_steps: number;\n  fix_rounds: number;\n  llm_calls: number;\n  duration_ms: number;\n  actions: string[];\n  validation_errors: string[];\n  error: string | null;\n}\n\n/** Options for constructing a MasarClient. */\nexport interface MasarClientOptions {\n  /** Base URL of the Masar server. Defaults to MASAR_URL env var or http://localhost:8080 */\n  baseUrl?: string;\n  /** Request timeout in milliseconds. Defaults to 120000 (2 minutes). */\n  timeoutMs?: number;\n  /** Optional callback for progress updates. */\n  onProgress?: (phase: string, detail: string) => void;\n}\n\n/**\n * HTTP client for the Masar schema generation server.\n *\n * Usage:\n * ```ts\n * const client = new MasarClient();\n * const result = await client.generate('Build a todo app with projects and tasks');\n * ```\n */\nexport class MasarClient {\n  private readonly baseUrl: string;\n  private readonly timeoutMs: number;\n  private readonly onProgress: ((phase: string, detail: string) => void) | null;\n\n  constructor(options?: MasarClientOptions) {\n    this.baseUrl = (options?.baseUrl ?? process.env['MASAR_URL'] ?? 'https://masar-345008351456.europe-west4.run.app').replace(/\\/$/, '');\n    this.timeoutMs = options?.timeoutMs ?? 120_000;\n    this.onProgress = options?.onProgress ?? null;\n  }\n\n  /**\n   * Generate an .orb schema from a natural language prompt.\n   *\n   * Sends the prompt to the Masar server which runs the full neural pipeline\n   * (goal parsing, GFlowNet generation, validation, LLM fix loop) and returns\n   * the result.\n   */\n  async generate(prompt: string): Promise<NeuralPipelineResult> {\n    this.onProgress?.('request', `Sending prompt to Masar at ${this.baseUrl}`);\n\n    const url = `${this.baseUrl}/generate`;\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ prompt }),\n        signal: controller.signal,\n      });\n\n      if (!response.ok) {\n        const body = await response.text().catch(() => '');\n        return makeErrorResult(\n          `Masar server returned ${response.status} ${response.statusText}${body ? `: ${body}` : ''}`,\n        );\n      }\n\n      const data: MasarGenerateResponse = await response.json() as MasarGenerateResponse;\n      this.onProgress?.('response', data.success ? 'Generation succeeded' : `Generation failed: ${data.error ?? 'unknown'}`);\n\n      return toNeuralPipelineResult(data);\n    } catch (err: unknown) {\n      if (err instanceof DOMException && err.name === 'AbortError') {\n        return makeErrorResult(`Masar request timed out after ${this.timeoutMs}ms`);\n      }\n      const message = err instanceof Error ? err.message : String(err);\n      return makeErrorResult(`Masar request failed: ${message}`);\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n}\n\n/**\n * Map the Masar server response to a NeuralPipelineResult.\n * Provides defaults for any missing fields so the result always satisfies the full interface.\n */\nfunction toNeuralPipelineResult(data: MasarGenerateResponse): NeuralPipelineResult {\n  return {\n    success: data.success,\n    validationPass: data.validation_pass,\n    compilationPass: false,\n    goalMatch: data.goal_match ?? 0,\n    totalSteps: data.total_steps ?? 0,\n    fixRounds: data.fix_rounds ?? 0,\n    llmCalls: data.llm_calls ?? 0,\n    durationMs: data.duration_ms ?? 0,\n    schema: data.schema ?? null,\n    schemaPath: null,\n    actions: data.actions ?? [],\n    validationErrors: data.validation_errors ?? [],\n    compilationErrors: [],\n    error: data.error ?? null,\n  };\n}\n\nfunction makeErrorResult(error: string): NeuralPipelineResult {\n  return {\n    success: false,\n    validationPass: false,\n    compilationPass: false,\n    goalMatch: 0,\n    totalSteps: 0,\n    fixRounds: 0,\n    llmCalls: 0,\n    durationMs: 0,\n    schema: null,\n    schemaPath: null,\n    actions: [],\n    validationErrors: [],\n    compilationErrors: [],\n    error,\n  };\n}\n"]}

package/dist/neural/masar-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Masar HTTP Client
+ *
+ * Calls the Masar server's /generate endpoint via HTTP instead of
+ * orchestrating the neural pipeline (GFlowNet + LLM fix loop) directly.
+ *
+ * The Masar server runs the full pipeline server-side and returns
+ * a NeuralPipelineResult-compatible response.
+ */
+import type { NeuralPipelineResult } from './types.js';
+/** Options for constructing a MasarClient. */
+export interface MasarClientOptions {
+    /** Base URL of the Masar server. Defaults to MASAR_URL env var or http://localhost:8080 */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 120000 (2 minutes). */
+    timeoutMs?: number;
+    /** Optional callback for progress updates. */
+    onProgress?: (phase: string, detail: string) => void;
+}
+/**
+ * HTTP client for the Masar schema generation server.
+ *
+ * Usage:
+ * ```ts
+ * const client = new MasarClient();
+ * const result = await client.generate('Build a todo app with projects and tasks');
+ * ```
+ */
+export declare class MasarClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly onProgress;
+    constructor(options?: MasarClientOptions);
+    /**
+     * Generate an .orb schema from a natural language prompt.
+     *
+     * Sends the prompt to the Masar server which runs the full neural pipeline
+     * (goal parsing, GFlowNet generation, validation, LLM fix loop) and returns
+     * the result.
+     */
+    generate(prompt: string): Promise<NeuralPipelineResult>;
+}

package/dist/neural/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Neural Pipeline Types
+ *
+ * Shared types for the GFlowNet-based schema generation pipeline.
+ */
+/**
+ * Structural goal vector extracted from a natural language prompt.
+ * Used by the GFlowNet to generate schema skeletons.
+ */
+export interface GoalSpec {
+    entities: number;
+    fields: number;
+    traits: number;
+    states: number;
+    transitions: number;
+    pages: number;
+    events: number;
+    effects: number;
+    entityNames: string[];
+    fieldNames: string[];
+    projectName: string;
+}
+export interface NeuralGenerateResult {
+    success: boolean;
+    schema?: Record<string, unknown>;
+    actions?: string[];
+    steps?: number;
+    goalMatch?: number;
+    error?: string;
+}
+export interface NeuralPipelineResult {
+    success: boolean;
+    validationPass: boolean;
+    compilationPass: boolean;
+    goalMatch: number;
+    totalSteps: number;
+    fixRounds: number;
+    llmCalls: number;
+    durationMs: number;
+    /** Generated .orb schema JSON string (returned by Masar server). */
+    schema: string | null;
+    /** @deprecated Use `schema` instead. Legacy field for file-based pipeline. */
+    schemaPath: string | null;
+    actions: string[];
+    validationErrors: string[];
+    compilationErrors: string[];
+    error: string | null;
+}
+export interface NeuralPipelineOptions {
+    provider: string;
+    model: string;
+    /** Working directory for writing schemas */
+    workDir: string;
+    maxFixRounds?: number;
+    samples?: number;
+    temperature?: number;
+    onProgress?: (phase: string, detail: string) => void;
+}
+/**
+ * Abstraction for running shell commands.
+ * Server uses temp files, CLI uses real paths, tests use mocks.
+ */
+export interface CommandExecutor {
+    /**
+     * Run `orbital validate` on a schema string or file path.
+     */
+    validateSchema(schema: string): Promise<ValidationResult>;
+    /**
+     * Run `orbital compile` on a schema file.
+     */
+    compileSchema?(schemaPath: string): Promise<CompileResult>;
+}
+/**
+ * Abstraction for running GFlowNet inference (Python subprocess).
+ */
+export interface PythonExecutor {
+    /**
+     * Run GFlowNet inference on a goal spec.
+     */
+    infer(goal: GoalSpec, options: InferOptions): Promise<InferResult>;
+}
+export interface InferOptions {
+    samples?: number;
+    temperature?: number;
+    bestOf?: boolean;
+}
+export interface InferResult {
+    samples: Array<{
+        schema: Record<string, unknown>;
+        actions: string[];
+        steps: number;
+        goal_match: number;
+        sample_idx: number;
+    }>;
+    goal: GoalSpec;
+    temperature: number;
+}
+export interface ValidationError {
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface ValidationResult {
+    success: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+export interface CompileResult {
+    success: boolean;
+    errors: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/agent",
-  "version": "2.0.5",
+  "version": "3.1.0",
   "description": "AI agent infrastructure for Almadar orbital schema generation",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +34,14 @@
     "./workspace": {
       "import": "./dist/workspace/index.js",
       "types": "./dist/workspace/index.d.ts"
+    },
+    "./neural": {
+      "import": "./dist/neural/index.js",
+      "types": "./dist/neural/index.d.ts"
+    },
+    "./builder": {
+      "import": "./dist/builder/index.js",
+      "types": "./dist/builder/index.d.ts"
     }
   },
   "files": [
@@ -45,7 +53,7 @@
   "dependencies": {
     "@almadar/core": ">=2.1.0",
     "@almadar/integrations": ">=2.0.1",
-    "@almadar/llm": ">=2.0.1",
+    "@almadar/llm": ">=2.2.0",
     "@almadar/patterns": ">=2.0.0",
     "@almadar/skills": ">=2.0.1",
     "langsmith": "^0.1.0",
@@ -84,6 +92,7 @@
     "@types/uuid": "^9.0.0",
     "@typescript-eslint/parser": "8.56.0",
     "deepagents": "^1.7.3",
+    "dotenv": "17.3.1",
     "eslint": "10.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",