@garrix82/reactgenie-dsl 1.0.0

package/README.md

@@ -0,0 +1,436 @@
+# ReactGenieDSL
+
+> Decorators, DSL execution, and LLM-backed semantic parsing for ReactGenie-style applications
+
+> Fork notice: this package snapshot is maintained as a thesis-project fork by [Omkar Mirgal](https://github.com/OmkarMirgal). For the original ReactGenie project, see [StanfordHCI/ReactGenie](https://github.com/StanfordHCI/ReactGenieDSL).
+
+## Introduction
+
+`@omkarfork/reactgenie-dsl` is the lower-level engine that powers Genie-based apps.
+
+It provides:
+
+- a decorated object model for app state and actions
+- a shared Redux-backed Genie store
+- a DSL interpreter for explicit command execution
+- an LLM-backed semantic parser that translates natural language into DSL
+- structured response generation for spoken and on-screen feedback
+- monitoring hooks for parser and response calls
+
+If you need the React integration layer, voice UI, route handling, or screen-aware `Current()` resolution, use `@omkarfork/reactgenie-lib` on top of this package.
+
+This README covers installation, quick start, feature overview, and the current public surface. For deeper implementation details and parser/runtime behavior, see [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md).
+
+## Feature Overview
+
+ReactGenieDSL currently includes:
+
+- Genie model base classes: `GenieObject`, `DataClass`, `HelperClass`
+- decorators: `GenieClass`, `GenieFunction`, `GenieProperty`, `GenieKey`
+- descriptor types: `ClassDescriptor`, `FuncDescriptor`, `FieldDescriptor`, `ParamDescriptor`
+- shared store bootstrap and access: `initGenie`, `genieDispatch`, `sharedStore`, `sharedState`, `AllGenieObjects`
+- DSL execution with `DslInterpreter`
+- stepwise execution introspection with `interpretSteps(...)`
+- JSON-friendly result shaping with `describe(...)` and `describeSteps(...)`
+- built-in collection operators:
+  - `matching(...)`
+  - `contains(...)`
+  - `between(...)`
+  - `equals(...)`
+  - `sort(...)`
+  - `index(...)`
+  - `length()`
+- natural-language orchestration with `NlInterpreter`
+- parser backends:
+  - `NlParserGroq`
+  - `NlParser` for OpenAI-compatible APIs
+- prompt generators:
+  - `BasicPromptGen`
+  - `DescriptorPromptGen`
+  - `ContextAwareDescriptorPromptGen`
+- parser monitoring with `getLLMMonitor(...)`
+- configurable sampling and provider selection
+- structured agent-response generation with normalized fallback handling
+
+## Parser Enhancements In The Current Implementation
+
+The current parser stack includes several implementation details beyond the older basic prompt flow:
+
+- context-aware prompt narrowing that selects only relevant class descriptions and examples
+- lexical ranking of descriptors/examples without an embeddings dependency
+- bounded caching of prompt selections for repeated utterances
+- recent-turn memory plus summarized older-turn context
+- runtime UI context injection for deictic utterances such as "this", "it", or "current"
+- explicit parser rules for:
+  - named parameters
+  - array-parameter brackets
+  - dotted accessor parameters such as `.receivedAt`
+- structured JSON output for command parsing and agent responses
+- lenient-first then strict structured-output retries
+- semantic validation of generated commands through a validator interpreter
+- automatic repair passes when the generated DSL is semantically invalid
+- optional stateful validation retry for the OpenAI Responses path
+- normalized response payloads and safe fallback responses when response synthesis fails
+- LangSmith-compatible monitoring hooks for prompt, token, latency, and cost tracking
+
+## Installation
+
+Install the current package and `reflect-metadata`:
+
+```bash
+npm install @omkarfork/reactgenie-dsl reflect-metadata
+```
+
+## TypeScript and Babel setup
+
+ReactGenieDSL relies on decorator metadata.
+
+TypeScript:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+Babel:
+
+```js
+plugins: [
+  ["@babel/plugin-proposal-decorators", { legacy: true }],
+  ["@babel/plugin-transform-class-properties", { loose: true }],
+  "babel-plugin-parameter-decorator",
+  "babel-plugin-reactgenie"
+]
+```
+
+Import `reflect-metadata` before any decorated Genie classes are evaluated.
+
+## Quick Start
+
+### 1. Define a Genie model
+
+```ts
+import "reflect-metadata";
+import {
+  DataClass,
+  GenieClass,
+  GenieFunction,
+  GenieKey,
+  GenieProperty,
+  int,
+} from "@omkarfork/reactgenie-dsl";
+
+@GenieClass("A counter the user can inspect or update")
+export class Counter extends DataClass {
+  @GenieKey
+  @GenieProperty("Stable counter identifier")
+  name: string;
+
+  @GenieProperty("Current count")
+  count: int;
+
+  static Examples = [
+    {
+      user_utterance: "increment the apples counter",
+      example_parsed: 'Counter.findByName(name: "apples").increment()',
+    },
+    {
+      user_utterance: "what is the apples count",
+      example_parsed: 'Counter.findByName(name: "apples").count',
+    },
+  ];
+
+  constructor({ name, count = 0 }: { name: string; count?: int }) {
+    super({ name });
+    this.name = name;
+    this.count = count;
+  }
+
+  static setup() {
+    Counter.CreateObject({ name: "apples", count: 2 });
+    Counter.CreateObject({ name: "oranges", count: 5 });
+  }
+
+  @GenieFunction("Return the default counter")
+  static current(): Counter {
+    return Counter.GetObject({ name: "apples" });
+  }
+
+  @GenieFunction("Find a counter by name")
+  static findByName({ name }: { name: string }): Counter {
+    return Counter.GetObject({ name });
+  }
+
+  @GenieFunction("Increase the counter by one")
+  increment(): this {
+    this.count += 1;
+    return this;
+  }
+}
+```
+
+Notes:
+
+- use `DataClass` for indexed, retrievable entities
+- use `HelperClass` for nested value objects
+- create objects with `CreateObject(...)`, not `new`
+- `@GenieFunction()` currently expects either no parameters or a single destructured object parameter
+
+### 2. Initialize Genie
+
+```ts
+import { initGenie } from "@omkarfork/reactgenie-dsl";
+
+const store = initGenie();
+```
+
+`initGenie()` initializes the shared store, applies registered modifiers, and runs `setup()` on already-registered classes.
+
+### 3. Execute explicit DSL
+
+```ts
+import { AllGenieObjects, DslInterpreter } from "@omkarfork/reactgenie-dsl";
+
+const descriptors = Object.values(AllGenieObjects).map(
+  (klass: any) => klass.ClassDescriptor
+);
+
+const interpreter = new DslInterpreter(descriptors);
+
+await interpreter.interpret('Counter.findByName(name: "apples").increment()');
+const value = await interpreter.interpret('Counter.findByName(name: "apples").count');
+const described = await interpreter.describe(value);
+```
+
+### 4. Parse natural language into DSL
+
+```ts
+import {
+  AllGenieObjects,
+  ClassDescriptor,
+  ExampleParse,
+  GenieObject,
+  NlInterpreter,
+} from "@omkarfork/reactgenie-dsl";
+
+const descriptors = Object.values(AllGenieObjects).map(
+  (klass: any) => klass.ClassDescriptor as ClassDescriptor<GenieObject>
+);
+
+const examples: ExampleParse[] = [
+  new ExampleParse(
+    "increment the apples counter",
+    'Counter.findByName(name: "apples").increment()'
+  ),
+  new ExampleParse(
+    "what is the apples count",
+    'Counter.findByName(name: "apples").count'
+  ),
+];
+
+const interpreter = new NlInterpreter(
+  descriptors,
+  process.env.LLM_API_KEY!,
+  undefined,
+  examples
+);
+
+const executionResult = await interpreter.interpret("increment the apples counter");
+```
+
+### 5. Generate a structured response
+
+```ts
+const response = await interpreter.respond(
+  "increment the apples counter",
+  'Counter.findByName(name: "apples").increment()',
+  JSON.stringify(await interpreter.dslInterpreter.describe(executionResult))
+);
+```
+
+The response payload shape is:
+
+```ts
+{
+  minimalText: string;
+  fullText: string;
+  type: "info" | "error" | "success" | "warning";
+  shouldSpeak: boolean;
+}
+```
+
+## Current DSL Capabilities
+
+ReactGenieDSL currently supports:
+
+- static calls such as `Order.current()`
+- instance calls such as `Order.current().placeOrder()`
+- property access such as `Order.current().status`
+- chained access such as `Order.All().sort(field: .dateTime, ascending: false)[0].restaurant.name`
+- array literals
+- negative indexing
+- collection filters through `matching`, `contains`, `between`, and `equals`
+- collection sorting through `sort`
+- collection indexing through `index(...)` or bracket syntax
+- collection length via `length()`
+
+Important parser rules:
+
+- parameter names must be explicit
+- accessor parameters for filters/sort must be dotted accessors such as `.name`, not quoted strings
+- when passing an array expression into a function parameter, the expression must be wrapped in `[...]`
+
+## Provider Configuration
+
+`NlInterpreter` supports `groq` and `openai` parser providers.
+
+### Groq example
+
+```ts
+const interpreter = new NlInterpreter(
+  descriptors,
+  process.env.LLM_API_KEY!,
+  undefined,
+  examples,
+  undefined,
+  {
+    parser: {
+      provider: "groq",
+      groq: {
+        model: "llama-3.3-70b-versatile",
+        baseUrl: "https://api.groq.com/openai/v1",
+        samplingParams: {
+          temperature: 0.2,
+          top_p: 1,
+          frequency_penalty: 0,
+          presence_penalty: 0,
+        },
+      },
+    },
+  }
+);
+```
+
+### OpenAI-compatible example
+
+```ts
+const interpreter = new NlInterpreter(
+  descriptors,
+  process.env.LLM_API_KEY!,
+  undefined,
+  examples,
+  undefined,
+  {
+    parser: {
+      provider: "openai",
+      openai: {
+        baseUrl: "https://api.openai.com/v1",
+        model: "gpt-4o-mini",
+        statefulValidationRetry: true,
+        samplingParams: {
+          temperature: 0.2,
+          top_p: 1,
+          frequency_penalty: 0,
+          presence_penalty: 0,
+        },
+      },
+    },
+  }
+);
+```
+
+Provider notes:
+
+- default provider is `groq`
+- `GENIE_PARSER_PROVIDER` can select the provider if config is omitted
+- OpenAI mode requires an explicit model
+- Groq mode defaults to `llama-3.3-70b-versatile`
+- base URLs are normalized internally to the expected OpenAI-compatible endpoints
+
+## Monitoring
+
+The NL stack exposes `getLLMMonitor(...)` and integrates with LangSmith-style telemetry.
+
+Monitoring supports:
+
+- prompt / completion token counts
+- cost metadata when the backend returns it
+- latency tracking
+- parser/response errors
+- optional telemetry bridges for error and message forwarding
+
+## Public API At a Glance
+
+### Model and decorators
+
+- `GenieObject`
+- `DataClass`
+- `HelperClass`
+- `GenieClass`
+- `GenieFunction`
+- `GenieProperty`
+- `GenieKey`
+- `ClassDescriptor`
+- `FuncDescriptor`
+- `FieldDescriptor`
+- `ParamDescriptor`
+- `int`
+- `float`
+- `LazyType`
+
+### Store and registry
+
+- `initGenie`
+- `genieDispatch`
+- `sharedStore`
+- `sharedState`
+- `AllGenieObjects`
+
+### DSL execution
+
+- `DslInterpreter`
+- `InterpreterError`
+- `ClassMissingError`
+- `FieldMissingError`
+- `FieldStaticError`
+- `FunctionMissingError`
+- `FunctionStaticError`
+- `InvalidParameterTypeError`
+
+### NL parsing and prompting
+
+- `NlInterpreter`
+- `NlParser`
+- `NlParserGroq`
+- `BasicPromptGen`
+- `DescriptorPromptGen`
+- `ContextAwareDescriptorPromptGen`
+- `PromptGen`
+- `ExampleParse`
+- `PromptSelectionConfig`
+- `PromptRuntimeContextSetter`
+- `RuntimeUiContext`
+- `PromptInteractionRecord`
+- `PromptInteractionRecorder`
+- `AgentResponsePayload`
+- `ResponseSeverity`
+- `SamplingParams`
+
+### Monitoring
+
+- `getLLMMonitor`
+- `LLMMonitorTelemetryBridge`
+
+## Documentation Split
+
+- `README.md`: install, quick start, feature overview, and public API summary
+- `DEVELOPER_GUIDE.md`: deeper package behavior, parser/runtime details, DSL semantics, provider configuration, and troubleshooting
+
+## License
+
+Apache-2.0

package/dist/__test__/dsl-descriptor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__test__/dsl-descriptor.test.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const example_descriptor_1 = require("./example_descriptor");
+test("Restaurant Description", async () => {
+    const description = example_descriptor_1.Restaurant._ClassDescriptor.description();
+    expect(description).toEqual("// A restaurant\n" +
+        "class Restaurant {\n" +
+        "\tstring name;\n" +
+        "\tFood[] menu;\n" +
+        "\tint rating;\n" +
+        "\tfloat priceGrade;\n" +
+        "\tstring cuisine;\n" +
+        "\tstring address;\n" +
+        "\tOrder[] orders;\n" +
+        "\t// All active restaurants\n" +
+        "\tstatic Restaurant[] all();\n" +
+        "\t// All active restaurants\n" +
+        "\tstatic Restaurant[] All();\n" +
+        "\t// The current restaurant\n" +
+        "\tstatic Restaurant current();\n" +
+        "\t// Book a table for a given date time\n" +
+        "\tvoid book(dateTime: DateTime? = `DateTime.today()`);\n" +
+        "\t// Book numbers tables for a given date time\n" +
+        "\tvoid bookTable(dateTime: DateTime?, number: int?);\n" +
+        "}");
+});
+//# sourceMappingURL=dsl-descriptor.test.js.map

package/dist/__test__/dsl-descriptor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl-descriptor.test.js","sourceRoot":"","sources":["../../lib/__test__/dsl-descriptor.test.ts"],"names":[],"mappings":";;AAAA,6DAAkD;AAElD,IAAI,CAAC,wBAAwB,EAAE,KAAK,IAAI,EAAE;IACxC,MAAM,WAAW,GAAG,+BAAU,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC;IAC9D,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CACzB,mBAAmB;QACnB,sBAAsB;QACpB,kBAAkB;QAClB,kBAAkB;QAClB,iBAAiB;QACjB,uBAAuB;QACvB,qBAAqB;QACrB,qBAAqB;QACrB,qBAAqB;QACrB,+BAA+B;QAC/B,gCAAgC;QAChC,+BAA+B;QAC/B,gCAAgC;QAChC,+BAA+B;QAC/B,kCAAkC;QAClC,2CAA2C;QAC3C,0DAA0D;QAC1D,kDAAkD;QAClD,wDAAwD;QACxD,GAAG,CACN,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/__test__/example_descriptor.d.ts

@@ -0,0 +1,125 @@
+import { ClassDescriptor, DataClass, HelperClass } from "../dsl-descriptor";
+import { ExampleParse } from "../nl";
+import { float, int, LazyType } from "../decorators";
+export declare let recentBooking: any;
+export declare class DateTime extends HelperClass {
+    private _date;
+    year: number;
+    month: number;
+    day: number;
+    dayOfWeek: string;
+    hour: number;
+    minute: number;
+    private updateDate;
+    static today(): DateTime;
+    static sunday: number;
+    static monday: number;
+    static tuesday: number;
+    static wednesday: number;
+    static thursday: number;
+    static friday: number;
+    static saturday: number;
+    static fromDate(date: Date): DateTime;
+    description(): {};
+    static compare(a: DateTime, b: DateTime): number;
+    constructor({ year, month, day, hour, minute, }: {
+        year?: number;
+        month?: number;
+        day?: number;
+        hour?: number;
+        minute?: number;
+    });
+    _getConstructorParams(): any;
+    addDateOffset({ year, month, day, hour, minute, }: {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+    }): this;
+    setDate({ year, month, day, hour, minute, day_of_the_week, }: {
+        year?: number;
+        month?: number;
+        day?: number;
+        hour?: number;
+        minute?: number;
+        day_of_the_week?: number;
+    }): this;
+    toString(): string;
+    static _ClassDescriptor: ClassDescriptor<DateTime>;
+}
+export declare class Food extends DataClass {
+    static _all: Food[];
+    static all(): Food[];
+    _price: float;
+    name: string;
+    price: float;
+    restaurant: LazyType<Restaurant>;
+    constructor({ name, price, restaurant, }: {
+        name: string;
+        price: float;
+        restaurant: LazyType<Restaurant>;
+    });
+    update(): Promise<void>;
+    description(): {};
+    static _ClassDescriptor: ClassDescriptor<Food>;
+}
+export declare class Order extends DataClass {
+    static _all: Order[];
+    static all(): Order[];
+    static _current: Order;
+    static current(): Promise<Order>;
+    orderId: string;
+    dateTime: DateTime;
+    foods: Food[];
+    restaurant: LazyType<Restaurant>;
+    constructor({ orderId, dateTime, foods, restaurant, }: {
+        orderId: string;
+        dateTime: DateTime;
+        foods: Food[];
+        restaurant: LazyType<Restaurant> | null;
+    });
+    addFoods({ foods }: {
+        foods: Food[];
+    }): void;
+    removeFoods({ foods }: {
+        foods: Food[];
+    }): void;
+    placeOrder(): void;
+    description(): {};
+    static _ClassDescriptor: ClassDescriptor<Order>;
+}
+export declare class Restaurant extends DataClass {
+    static _all: Restaurant[];
+    orders: Order[];
+    static all(): Restaurant[];
+    description(): {};
+    createFood(name: string, price: float): Food;
+    createOrder(orderId: string, dateTime: DateTime, foods: Food[]): Promise<Order>;
+    static current(): Promise<Restaurant>;
+    book({ dateTime }: {
+        dateTime?: DateTime;
+    }): void;
+    bookTable({ dateTime, number }: {
+        dateTime?: DateTime;
+        number?: int;
+    }): void;
+    name: string;
+    menu: Food[];
+    rating: int;
+    priceGrade: float;
+    cuisine: string;
+    address: string;
+    constructor({ name, menu, rating, priceGrade, cuisine, address, }: {
+        name: string;
+        menu: Food[];
+        rating: number;
+        priceGrade: number;
+        cuisine: string;
+        address: string;
+    });
+    static _ClassDescriptor: ClassDescriptor<Restaurant>;
+}
+export declare const allDescriptors: ClassDescriptor<import("../dsl-descriptor").GenieObject>[];
+export declare const classDescriptions: string[];
+export declare const examples: ExampleParse[];