@autochitect/engine 1.0.0 → 1.1.0

package/README.md

@@ -1,23 +1,23 @@
-# forecaster
+# @autochitect/engine
 
-A 245KB WebAssembly financial modeling engine. Write cost models in a purpose-built DSL, get instant evaluation with a full dependency graph. Runs entirely client-side — no server, no latency, no data leaving the browser.
+A 245KB WebAssembly cost estimation engine. Define cost models in a purpose-built DSL, get instant estimates with full dependency tracing. Runs entirely client-side — no server, no latency, no data leaving the browser.
 
 ## Install
 
 ```bash
-npm install forecaster
+pnpm install @autochitect/engine
 ```
 
 ## Quick start
 
 ```javascript
-import { createEngine } from 'forecaster';
+import { createEngine } from '@autochitect/engine';
 
 const engine = await createEngine(
-  new URL('forecaster/engine.wasm', import.meta.url)
+  new URL('@autochitect/engine/engine.wasm', import.meta.url)
 );
 
-const result = engine.evaluate(`
+const result = engine.estimate(`
   revenue: Input
   cost_ratio: Input
   costs = revenue * cost_ratio
@@ -35,66 +35,133 @@ console.log(result.results);
 
 **`result.results`** — computed values for every variable.
 
-**`result.graph`** — the full dependency DAG showing how each value was derived. Nodes have `kind` (input, constant, formula, map, scan) and edges show data flow. Use this to build audit trails, trace calculations back to source inputs, or render interactive visualizations.
+**`result.graph`** — the full dependency DAG showing how each value was derived. Nodes have `kind` (input, constant, formula, map, scan) and edges show data flow. Build audit trails, trace calculations back to source inputs, or render interactive cost breakdowns.
 
 **`result.errors`** / **`result.warnings`** — with line and column numbers.
 
 ## The DSL
 
-The language is deliberately small. It's not a spreadsheet formula language — it's designed for financial modeling specifically.
+The language is deliberately small. It's designed for cost estimation and financial modeling specifically.
 
 ```
-# Declarations
+# Inputs — bind to external data (your JSON)
 revenue: Input("annual_revenue")
+headcount: Input
+
+# Constants — fixed values
 tax_rate: Const(0.21)
+avg_salary: Const(85000)
+
+# Params — tunable scenario knobs
 growth: Param
 
-# Formulas
+# Formulas — define cost relationships
+labor_cost = headcount * avg_salary
 gross_profit = revenue * (1 - cost_ratio)
 net_income = gross_profit * (1 - tax_rate)
 
-# Array operations
+# Array operations — project over time
 periods = SEQUENCE(12, 1, 1)
 monthly = MAP(periods, LAMBDA(p, revenue / 12 * POWER(1 + growth, p)))
 
-# Accumulation
+# Accumulation — running totals
 cumulative = SCAN(monthly, 0, LAMBDA(acc, m, acc + m))
 ```
 
-**Inputs** bind to external data (your JSON). **Constants** are fixed values. **References** alias other variables.
+**Inputs** bind to external data (your JSON). **Constants** are fixed values. **Params** are tunable scenario knobs.
 
 **MAP** transforms arrays element-wise. **SCAN** accumulates (like reduce, but returns intermediate results). **LAMBDA** defines inline functions with named parameters.
 
-The engine compiles this into a directed acyclic graph, topologically sorts it, and evaluates in one pass. The graph is immutable — switching scenarios just swaps the input context, so it's instant.
+The engine compiles this into a directed acyclic graph, topologically sorts it, and estimates in one pass. The graph is immutable — switching scenarios just swaps the input context, so it's instant.
+
+## Node.js usage
+
+```javascript
+import { createEngine } from '@autochitect/engine';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const wasmPath = require.resolve('@autochitect/engine/engine.wasm');
+const engine = await createEngine(wasmPath);
+
+const result = engine.estimate(`
+  headcount: Input
+  avg_salary: Const(85000)
+  benefits_rate: Const(0.3)
+
+  labor_cost = headcount * avg_salary
+  benefits = labor_cost * benefits_rate
+  total_people_cost = labor_cost + benefits
+`, {
+  headcount: 12,
+});
+
+console.log(result.results);
+// {
+//   headcount: 12,
+//   avg_salary: 85000,
+//   benefits_rate: 0.3,
+//   labor_cost: 1020000,
+//   benefits: 306000,
+//   total_people_cost: 1326000
+// }
+```
 
 ## Browser usage
 
 ```html
 <script type="module">
-  import { createEngine } from './node_modules/forecaster/index.mjs';
-  const engine = await createEngine('./node_modules/forecaster/engine.wasm');
-  const result = engine.evaluate('x = 2 + 2', {});
-  document.body.textContent = JSON.stringify(result.results);
+  import { createEngine } from './node_modules/@autochitect/engine/index.mjs';
+
+  const engine = await createEngine(
+    new URL('./node_modules/@autochitect/engine/engine.wasm', import.meta.url)
+  );
+
+  const result = engine.estimate(`
+    units: Input
+    price_per_unit: Input
+    discount_rate: Input
+
+    subtotal = units * price_per_unit
+    discount = subtotal * discount_rate
+    total = subtotal - discount
+  `, {
+    units: 1000,
+    price_per_unit: 49.99,
+    discount_rate: 0.15,
+  });
+
+  console.log(result.results);
+  // { units: 1000, price_per_unit: 49.99, discount_rate: 0.15,
+  //   subtotal: 49990, discount: 7498.5, total: 42491.5 }
 </script>
 ```
 
-## Node.js usage
+When using a bundler (Vite, webpack, etc.), import the WASM file directly:
 
 ```javascript
-import { createEngine } from 'forecaster';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { createEngine } from '@autochitect/engine';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const wasmPath = join(__dirname, 'node_modules/forecaster/engine.wasm');
-const engine = await createEngine(wasmPath);
+const engine = await createEngine(
+  new URL('@autochitect/engine/engine.wasm', import.meta.url)
+);
 ```
 
 ## Options
 
 ```javascript
-// Skip the dependency graph for faster evaluation
-engine.evaluate(source, inputs, { graph: false });
+// Skip the dependency graph for faster estimation
+engine.estimate(source, inputs, { graph: false });
+```
+
+## TypeScript
+
+Full type definitions are included. Key types:
+
+```typescript
+import type { Engine, EstimateResult, EstimateOptions } from '@autochitect/engine';
 ```
 
 ## License

package/index.d.ts

@@ -1,4 +1,4 @@
-export interface EvalResult {
+export interface EstimateResult {
   success: boolean;
   results: Record<string, number | number[] | string | null>;
   errors: Array<{ message: string; line: number; col: number }>;
@@ -16,12 +16,12 @@ export interface EvalResult {
   };
 }
 
-export interface EvalOptions {
+export interface EstimateOptions {
   graph?: boolean;
 }
 
 export interface Engine {
-  evaluate(source: string, inputs?: Record<string, unknown>, options?: EvalOptions): EvalResult;
+  estimate(source: string, inputs?: Record<string, unknown>, options?: EstimateOptions): EstimateResult;
 }
 
 export function createEngine(wasmSource: string | Response | ArrayBuffer): Promise<Engine>;

package/index.mjs

@@ -112,11 +112,11 @@ export async function createEngine(wasmSource) {
   }
 
   return {
-    evaluate(source, inputs = {}, options = {}) {
+    estimate(source, inputs = {}, options = {}) {
       const includeGraph = options.graph !== false;
       const src = writeString(source);
       const json = writeString(JSON.stringify(inputs));
-      const resultLen = instance.exports.wasm_eval(
+      const resultLen = instance.exports.wasm_estimate(
         src.ptr, src.len,
         json.ptr, json.len,
         includeGraph ? 1 : 0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@autochitect/engine",
-  "version": "1.0.0",
-  "description": "A 245KB WebAssembly financial modeling engine. Define cost models in a purpose-built DSL, get instant evaluation with full dependency tracing. No server required.",
+  "version": "1.1.0",
+  "description": "A 245KB WebAssembly financial modeling engine. Define cost models in a purpose-built DSL, get instant estimates with full dependency tracing. No server required.",
   "license": "MIT",
   "type": "module",
   "main": "index.mjs",