{"id":18091204,"url":"https://github.com/xavidop/genkit-nlu","last_synced_at":"2025-04-13T05:44:51.136Z","repository":{"id":259249835,"uuid":"874660584","full_name":"xavidop/genkit-nlu","owner":"xavidop","description":"The NLU powered by LLMs that just works","archived":false,"fork":false,"pushed_at":"2025-02-20T00:23:47.000Z","size":766,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T05:44:46.258Z","etag":null,"topics":["firebase","firebase-genkit","generative-ai","genkit","llm","openai"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xavidop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-18T08:27:54.000Z","updated_at":"2025-02-20T00:22:36.000Z","dependencies_parsed_at":"2024-10-30T22:33:42.719Z","dependency_job_id":null,"html_url":"https://github.com/xavidop/genkit-nlu","commit_stats":null,"previous_names":["xavidop/genkit-nlu"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Fgenkit-nlu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Fgenkit-nlu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Fgenkit-nlu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xavidop%2Fgenkit-nlu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xavidop","download_url":"https://codeload.github.com/xavidop/genkit-nlu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670520,"owners_count":21142901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firebase","firebase-genkit","generative-ai","genkit","llm","openai"],"created_at":"2024-10-31T18:10:02.951Z","updated_at":"2025-04-13T05:44:51.129Z","avatar_url":"https://github.com/xavidop.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NLU Flow Project\n\nThis project implements a Natural Language Understanding (NLU) flow using Firebase Genkit AI and Firebase Functions. The NLU flow detects intents and extracts entities from a given text input.\n\nthis project uses GitHub Models using the Genkit GitHub models plugin.\n\n\u003c!-- TOC --\u003e\n\n- [NLU Flow Project](#nlu-flow-project)\n  - [Project Structure](#project-structure)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n  - [Development](#development)\n    - [Linting](#linting)\n    - [Building](#building)\n    - [Serving](#serving)\n    - [Deploying](#deploying)\n    - [Development Workflow](#development-workflow)\n  - [Code Explanation](#code-explanation)\n  - [Prompt Definition](#prompt-definition)\n  - [Usage](#usage)\n    - [Intents](#intents)\n    - [Entities](#entities)\n    - [Example](#example)\n  - [License](#license)\n  - [Contributing](#contributing)\n  - [Contact](#contact)\n\n\u003c!-- /TOC --\u003e\n\n\n## Project Structure\n\n```\n.firebaserc\n.gitignore\nfirebase.json\nfunction/\n  .eslintrc.js\n  .gitignore\n  nlu/\n    entities.yml\n    intents.yml\n  package.json\n  prompts/\n    nlu.prompt\n  src/\n    index.ts\n  tsconfig.dev.json\n  tsconfig.json\n```\n\n## Prerequisites\n\n- Node.js v20\n- Firebase CLI\n- Genkit CLI\n- TypeScript\n- Github Account\n\n## Installation\n\n1. Clone the repository:\n    ```sh\n    git clone https://github.com/xavidop/genkit-nlu.git\n    cd genkit-nlu\n    ```\n\n## Configuration\n\n1. Ensure you have the necessary Firebase configuration files (`firebase.json`, `.firebaserc`).\n\n2. Update the `nlu/intents.yml` and `nlu/entities.yml` files with your intents and entities.\n\n## Development\n\n### Linting\n\nRun ESLint to check for code quality issues:\n```sh\nnpm run lint\n```\n\n### Building\n\nCompile the TsypeScript code:\n```sh\nnpm run build\n```\n\n### Serving\n\nServe the functions locally:\n```sh\nnpm run serve\n```\n\n### Deploying\n\nDeploy the functions to Firebase:\n```sh\nnpm run deploy\n```\n\n### Development Workflow\nRun in the root directory:\n```sh\nnpm run genkit:start\n```\n\n## Code Explanation\n* Configuration: The `genkit` function is called to set up the Genkit environment with plugins for Firebase, GitHub, and Dotprompt. It also sets the log level to \"debug\".\n\n```typescript\nconst ai = genkit({\n  plugins: [github()],\n  promptDir: 'prompts',\n  model: openAIGpt4o\n});\nlogger.setLogLevel('debug');\n```\n\n* Flow Definition: The nluFlow is defined using the onFlow function.\n   * Configuration: The flow is named `nluFlow` and has input and output schemas defined using zod. The input schema expects an object with a text string, and the output schema is a string. The flow does not require authentication (noAuth).\n   * nluFlow: The flow processes the input:\n        * Schema Definition: Defines an `nluOutput` schema with intent and entities.\n        * Prompt Reference: Gets a reference to the \"nlu\" dotprompt file.\n        * File Reading: Reads `intents.yml` and `entities.yml` files.\n        * Prompt Generation: Uses the `nluPrompt` to generate output based on the input text and the read intents and entities.\n        * Return Output: Returns the generated output with type `nluOutput`.\n```typescript\nconst nluOutput = ai.defineSchema(\n  \"nluOutput\",\n  z.object({\n    intent: z.string(),\n    entities: z.map(z.string(), z.string()),\n  }),\n);\n\nexport const nluFlow = ai.defineFlow(\n  {\n    name: \"nluFlow\",\n    inputSchema: z.object({text: z.string()}),\n    outputSchema: z.string(),\n  },\n  async (toDetect) =\u003e {\n\n    const nluPrompt = ai.prompt\u003c\n                        z.ZodTypeAny, // Input schema\n                        typeof nluOutput, // Output schema\n                        z.ZodTypeAny // Custom options schema\n                      \u003e(\"nlu\");\n\n    const intents = readFileSync('nlu/intents.yml','utf8');\n    const entities = readFileSync('nlu/entities.yml','utf8');\n\n    const result = await nluPrompt({\n        intents: intents,\n        entities: entities,\n        user_input: toDetect.text,\n    });\n\n    return JSON.stringify(result.output);\n  },\n);\n\nexport const nluFunction = onCallGenkit({\n  authPolicy: () =\u003e true, // Allow all users to call this function. Not recommended for production.\n}, nluFlow);\n\n```\n\n## Prompt Definition \n\nThis `nlu.prompt` file defines a prompt for a Natural Language Understanding (NLU) model. Here's a breakdown of its components:\n\n1. **Model Specification**:\n   ```yaml\n   model: github/gpt-4o\n   ```\n   This specifies the LLM model to be used, in this case, `github/gpt-4o`.\n\n2. **Input Schema**:\n   ```yaml\n   input:\n     schema:\n       intents: string\n       entities: string\n       user_input: string\n   ```\n   This defines the input schema for the prompt. It expects three string inputs:\n   - `intents`: A string representing the intents.\n   - `entities`: A string representing the entities.\n   - `user_input`: A string representing the user's input text.\n\n3. **Output Specification**:\n   ```yaml\n   output:\n     format: json\n     schema: nluOutput\n   ```\n   This defines the output format and schema. The output will be in JSON format and should conform to the `nluOutput` schema.\n\n4. **Prompt Text**:\n   ```yaml\n   ---\n   You are a NLU that detects intents and extract entities from a given text.\n\n   you have these intents and utterances:\n   {{intents}}\n   You also have these entities:\n   {{entities}}\n\n   The user says: {{user_input}}\n   Please specify the intent detected and the entity detected\n   ```\n   This is the actual prompt text that will be used by the model. It provides context and instructions to the model:\n   - It describes the role of the model as an NLU system.\n   - It includes placeholders (`{{intents}}`, `{{entities}}`, `{{user_input}}`) that will be replaced with the actual input values.\n   - It asks the model to specify the detected intent and entity based on the provided user input.\n\n## Usage\n\nThe main NLU flow is defined in index.ts. It reads intents and entities from YAML files and uses a prompt defined in `nlu.prompt` to generate responses.\n\n### Intents\nThe intents are defined in the `nlu/intents.yml` file. Each intent has a name and a list of training phrases.\n\nAs an example, the following intent is defined in the `nlu/intents.yml` file:\n```yaml\norder_shoes:\n  utterances: \n    - I want a pair of shoes from {shoes_brand}\n    - a shoes from {shoes_brand}\n```\nThe format is as follows:\n```yaml\nintent-name:\n  utterances:\n    - training phrase 1\n    - training phrase 2\n    - ...\n```\n\n### Entities\nThe entities are defined in the `nlu/entities.yml` file. Each entity has a name and a list of synonyms.\n\nAs an example, the following entity is defined in the `nlu/entities.yml` file:\n```yaml\nshoes_brand:\n  examples:\n    - Puma\n    - Nike\n```\nThe format is as follows:\n```yaml\nentity-name:\n  examples:\n    - synonym 1\n    - synonym 2\n    - ...\n```\n\n### Example\n\nTo trigger the NLU flow, send a request with the following structure:\n```json\n{\n  \"text\": \"Your input text here\"\n}\n```\n\nThe response will be a JSON object with the following structure:\n```json\n{\n  \"intent\": \"intent-name\",\n  \"entities\": {\n    \"entity-name\": \"entity-value\"\n  }\n}\n```\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## Contact\n\nFor any questions or issues, please open an issue in the repository.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavidop%2Fgenkit-nlu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxavidop%2Fgenkit-nlu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavidop%2Fgenkit-nlu/lists"}