GeminiBranch

This library performs conditional branching using natural language, powered by Google's Gemini API. Think of it as a natural language if/else or switch statement.

Features

• Natural Language branching: Branch complex, nuanced, or subjective conditions that are difficult to express with traditional code.
• Dynamic Branching: Select the most appropriate option from a set of choices based on a natural language prompt.
• Simple & Typed API: Easy-to-use, typed interface for seamless integration into TypeScript projects.
• Error Handling: Built-in error handling for API failures and unexpected responses.

Installation

npm install gemini-branch

Usage

First, obtain a Google Gemini API key. You can get one from the Google AI Studio.

import { GeminiBranch } from 'gemini-branch';
import type { GeminiBranchResult } from 'gemini-branch';

let globalBranchResult: GeminiBranchResult | null = null;

globalBranchResult = await GeminiBranch({
    condition: "Which is the morning greeting?",
    choices: ["good morning", "hello", "good evening"],
    apiKey: "YOUR GEMINI API KEY",
    model: "gemma-3-27b-it",
});

console.log(globalBranchResult)
// { response: true, result: 'good morning', message: 'Success' }

Model Selection

You need to select a model from the Gemini or Gemma 3 model list.

API Reference

GeminiBranch is the main function that performs the conditional branching.

GeminiBranchOptions

| Parameter | Type | Description | Required | |-----------|------|-------------|----------| | condition | string | The natural language condition used for branching. | Yes | | choices | string[] | A list of candidate values. Gemini selects the single best-matching option. | Yes | | apiKey | string | Your Google Gemini API Key. | Yes | | model | string | The model to use for branching. | Yes | | else | string | A fallback value returned when no choice sufficiently matches the condition. | No | | consoleErrors | boolean | Log internal errors to the console. Default is false. | No |

GeminiBranchResult

| Parameter | Type | Description | |-----------|------|-------------| | response | boolean | true : The library executed correctly (including when the fallback else value is returned). false : An internal error occurred (API failure, schema violation, etc.). | | result | string | On success, a Gemini-selected value from choices or the fallback (else) value; on failure, "" or the else value if provided. | | message | string | Error message on failure, "Success" on success, "No matching choice" when else is selected |

⚠️ If else is not provided, the model is instructed to output "" when no choice matches.

License

This project is licensed under the MIT License. See the LICENSE file for details.