From 310649e434bf1d6d1b3092880b9e731422e807c5 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
<161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 15 Jan 2026 19:41:10 +0000
Subject: [PATCH] docs: simplify README.md
Replaced the detailed README.md with a simpler version that provides a brief overview of the project and a "Getting Started" guide.
---
README.md | 841 ++----------------------------------------------------
1 file changed, 16 insertions(+), 825 deletions(-)
diff --git a/README.md b/README.md
index ea22ae6..bf13752 100644
--- a/README.md
+++ b/README.md
@@ -1,847 +1,38 @@
-# dataprompt: prompts with data superpowers
+# Dataprompt
-> Status: Alpha
+Dataprompt is a metaframework for creating data-driven AI prompts. It allows you to combine prompt engineering with file-based routing, creating self-contained `.prompt` files that define your prompts, data sources, and post-generation actions.
-## Spin up dataprompt in seconds with Project IDX
+## Key Features
-
-
-
-
-
-
-
+* **Single File Prompts:** Define your prompts, data sources, and actions in a single `.prompt` file.
+* **File-Based Routing:** The path to your `.prompt` file determines its API endpoint.
+* **Data Integration:** Fetch data from external sources and use it in your prompts.
+* **Scheduled Tasks:** Automatically execute prompts on a schedule.
+* **Extensible:** Create custom plugins to add new data sources, actions, and triggers.
-## Single File Prompts
-dataprompt is a metaframework for prompt files, combining the power of prompt engineering with file-based routing. It lets you create self-contained "Single File Prompts" — `.prompt` files that define your prompts, data sources, and post-generation actions, all in one place. Think of it as Astro for AI prompts, bringing structure and organization to your AI development workflow.
+## Getting Started
-## Quick Start
-
-### Install and setup
+### Installation
```bash
-npm i dataprompt genkit
-# or use the dataprompt CLI
-npx dataprompt create
+npm install dataprompt genkit
```
### Create a `.prompt` file
-In your `prompts` directory, create a file like `prompts/[page].prompt`:
+Create a file named `hello.prompt` in your `prompts` directory:
```hbs
---
-model: googleai/gemini-2.5-flash
-data.prompt:
- sources:
- fetch:
- news: https://api.hnpwa.com/v0/news/{{request.params.page}}.json
-output:
- schema: HNAnalysisSchema
+model: googleai/gemini-1.5-flash
---
-Analyse the articles below.
-
-{{json news}}
+Hello, world!
```
-### Run the dataprompt dev server
+### Run the dev server
```bash
npx dataprompt dev
```
-This starts a development server that serves your prompts as a JSON API.
-
-## Example project structure
-
-```
-project/
-├─ prompts/
-│ ├─ hn/
-│ │ ├─ [page].prompt
-│ ├─ hello.prompt
-├─ schema.ts
-├─ dataprompt.config.js (optional)
-├─ package.json
-```
-
-## Scheduled Tasks with node-cron
-
-dataprompt supports triggers to automatically execute prompts. The most common are scheduled tasks using `node-cron`. Unlike file-based routes where the URL of your JSON API is determined by the location of the .prompt file, the `schedule` trigger is useful for background processes that need to execute periodically without a request.
-
-
-```hbs
----
-model: googleai/gemini-2.5-flash
-data.prompt:
- trigger:
- schedule:
- cron: '* * * * *' # Runs every minute
- sources:
- fetch:
- news: https://api.hnpwa.com/v0/news/1.json
-output:
- schema: HNAnalysisSchema
----
-Analyze these stories from Hacker News.
-
-{{json news}}
-```
-
-## dataprompt CLI and Config
-
-The dataprompt CLI provides commands to help you develop and manage your dataprompt projects.
-
-* `dataprompt dev`: Starts the dataprompt development server. It watches your `.prompt` files for changes and automatically reloads the server.
-* `dataprompt create`: Creates a new dataprompt project with a basic directory structure and configuration.
-
-### dataprompt.config.js
-
-The `dataprompt.config.js` file allows you to configure various aspects of dataprompt, such as the prompts directory, schema file, and plugins.
-
-```js
-// dataprompt.config.js
-/** @type {import('dataprompt').DatapromptConfig} */
-export default {
- promptsDir: 'my-prompts',
- schemaFile: 'my-schema.ts',
-};
-// This is not needed unless you want to change defaults
-```
-
-#### Config Options
-
-* `promptsDir`: (string, default: `'prompts'`) The directory where your `.prompt` files are located. This path is resolved relative to the project root.
-* `schemaFile`: (string, default: `'schema.ts'`) The path to your schema file, which exports Zod schemas for structured output. This path is resolved relative to the project root.
-* `plugins`: (DatapromptPlugin[], default: `[]`) An array of dataprompt plugins to register.
-* `genkitPlugins`: (Plugin[], default: `[]`) An array of Genkit plugins to use. If provided, they will be used to initialize the default Genkit instance.
-* `secrets`: (DatapromptSecrets, default: `process.env`) An object containing secret keys, such as API keys. See Secrets.
-* `genkit`: (Genkit, default: `getGenkit()`) A pre-configured Genkit instance to use. If not provided, dataprompt will create a default instance with the Google AI provider (if a key is present) or use the provided `genkitPlugins`.
-* `rootDir`: (string, default: project root) This option sets a custom root directory. This is useful when used in a monorepo setup.
-
-### Secrets
-
-dataprompt automatically looks for the following environment variables:
-
-* `GEMINI_API_KEY`: (Preferred) API key for the Google AI Gemini model.
-* `GOOGLEAI_API_KEY`: (Legacy) API key for the Google AI Gemini model.
-* `GOOGLE_APPLICATION_CREDENTIALS`: Path to a Firebase service account key file.
-
-You can also set these secrets in your `dataprompt.config.{js,ts}` file:
-
-```ts
-// dataprompt.config.ts
-export default {
- secrets: {
- GEMINI_API_KEY: 'YOUR_API_KEY',
- GOOGLE_APPLICATION_CREDENTIALS: '/path/to/serviceAccountKey.json',
- },
-};
-```
-
-**Warning:** Never check your secrets into version control. Use environment variables or a secrets management solution instead.
-
-These options are set for the default genkit instance. If you provide your own genkit instance, they are still set, but you will need to configure them yourself.
-
-## Understanding the dotprompt Format
-
-dataprompt extends the [dotprompt](https://github.com/google/dotprompt/) format to add data sources and actions to your prompts. The `data.prompt` property in your YAML frontmatter defines these extensions.
-
-### dotprompt
-
-The dotprompt format defines several properties:
-
-* `model`: (string) The name of the Genkit model to use.
-* `config`: (object) Configuration options for the model, such as temperature.
-* `input`: (object) Defines the schema for the prompt's input. *dataprompt does not use this directly*, it will dynamically infer it from the `request` object and any data sources that are defined.
-* `output`: (object) Defines the schema for the prompt's output.
-
-```hbs
----
-model: googleai/gemini-2.5-flash
-input:
- # not needed in data.prompt
- # input is generated from the sources and the request
- schema: HNStories
-output:
- schema: HNAnalysisSchema
----
-
-{{#each page.items as |story|}}
- - {{story.title}}
-{{/each}}
----
-```
-
-### Zod Schemas and the Schema File
-
-Structured output is declared using [Zod](https://zod.dev/) schemas that are exported from a designated schema file. This allows you to define the structure and types of the data returned by your prompts, ensuring consistency and type safety.
-
-By default, dataprompt is set up to automatically use `schema.ts` in the `tsconfig.json`'s `"outDir"` option, which is normally `"dist"`. This means that dataprompt will look for a compiled `schema.js` file in your output directory. You can customize this behavior using the `schemaFile` option in your `dataprompt.config.js` file.
-
-Example `schema.ts`:
-
-```ts
-// schema.ts
-import { z } from 'genkit';
-
-export const StorySchema = z.object({
- id: z.number(),
- by: z.string(),
- descendants: z.number().optional(),
- kids: z.array(z.number()).optional(),
- score: z.number(),
- time: z.number(),
- title: z.string(),
- type: z.string(),
- url: z.string().optional(),
- text: z.string().optional()
-});
-
-export const HNAnalysisSchema = z.object({
- top5: z.object({
- pageA: z.array(StorySchema),
- pageB: z.array(StorySchema),
- }).describe("Top 5 themes and topics for each page."),
- dominantThemesAndTopics: z.object({
- pageA: z.string(),
- pageB: z.string(),
- }).describe("Dominant themes and topics for each page."),
- keyDifferencesAndSimilarities: z.string().describe("Key differences and similarities between the themes and topics of the pages."),
- interestingInsightsTrendsPatterns: z.string().describe("Interesting insights, trends, patterns, or shifts observed in the comparison."),
- mostProminentThemes: z.object({
- pageA: z.array(z.string()),
- pageB: z.array(z.string()),
- }).describe("Most prominent themes for each page."),
- significantChanges: z.array(z.object({
- change: z.string().describe("Description of a significant change in themes, topics, or content types."),
- })).describe("Significant changes in themes, topics, or content types between the pages.").optional(),
-});
-```
-
-### Data Sources
-
-The `sources` API allows you to fetch external data and make it available within your prompts. You declare a source namespace and then define variables within that namespace, assigning them configuration options used to populate them with data. These variables can then be used in the template below.
-
-Example:
-
-```hbs
----
-model: googleai/gemini-2.5-flash
-data.prompt:
- sources:
- fetch:
- # The page variable will contain the JSON data fetched from the API.
- page: https://api.hnpwa.com/v0/news/1.json
-output:
- schema: HNAnalysisSchema
----
-
-{{#each page.items as |story|}}
- - {{story.title}}
-{{/each}}
-```
-
-### Result - Data Actions
-
-The `result` API enables you to perform actions on the output generated by your prompt. You declare an action namespace and then define actions within that namespace, providing configuration details on how they should operate post-generation. The generated `output` variable is provided for you to perform actions on the output generation. Any variables created in `sources` are also available for use in `result`.
-
-Example:
-
-```hbs
----
-model: googleai/gemini-2.5-flash
-data.prompt:
- sources:
- fetch:
- news: https://api.hnpwa.com/v0/news/1.json
- result:
- firestore:
- push: ['/news_summaries', output]
-output:
- schema: HNAnalysisSchema
----
-
-Summarize the following news articles:
-
-{{#each news.articles as |article|}}
- - {{article.title}}
- - {{article.content}}
-{{/each}}
-```
-
-### The Request Object
-
-Every prompt has access to a `request` object, which can be used as a template variable. This object contains information about the incoming request, such as the method, URL, headers, parameters, and query string. You can access any properties populated on the `RequestContext` type, which is a serialized version of a Request object. The `RequestContextSchema` is:
-
-```ts
-export const RequestContextSchema = z.object({
- method: z.string().optional(),
- url: z.string(),
- headers: z.record(z.string(), z.string()).optional(),
- params: z.record(
- z.string(),
- z.union([z.string(), z.array(z.string())])
- ).optional(),
- query: z.record(
- z.string(),
- z.union([z.string(), z.array(z.string())])
- ).optional(),
- body: z.object({
- json: z.any().optional(),
- form: z.record(z.string(), z.any()).optional(),
- text: z.string().optional()
- }).optional(),
- requestId: z.string().optional()
-});
-
-export type RequestContext = z.infer;
-```
-
-Example:
-
-```hbs
----
-model: googleai/gemini-2.5-flash
-output:
- schema: ExampleSchema
----
-
-The URL is: {{request.url}}
-The method is: {{request.method}}
-The parameter 'id' is: {{request.params.id}}
-```
-
-### Date Format Helper
-
-The `dateFormat` helper is a Handlebars helper that allows you to format dates within your prompts. It can be used in either the frontmatter or the template.
-
-Syntax:
-
-```hbs
-{{dateFormat value format="yyyy-MM-dd HH:mm:ss"}}
-```
-
-* `value`: A string representing a date command or a relative date. Supported commands are `today` and `yesterday`. Relative dates can be specified using a number followed by a unit of time (e.g., `-1 day`, `+2 hours`).
-* `format`: An optional format string using [date-fns](https://date-fns.org/) syntax. Defaults to `yyyy-MM-dd`.
-
-Examples:
-
-```hbs
-Today's date: {{dateFormat "today" format="yyyy-MM-dd"}}
-Yesterday's date: {{dateFormat "yesterday" format="MM/dd/yy"}}
-Date one day ago: {{dateFormat "-1 day" format="yyyy-MM-dd"}}
-Date in 2 hours: {{dateFormat "+2 hours" format="yyyy-MM-dd HH:mm:ss"}}
-```
-
-### Triggers
-
-Triggers allow you to automate the execution of your prompts based on specific events or schedules. Currently, the only supported trigger type is `ScheduledTask` from `node-cron`, but different trigger types are on the roadmap.
-
-Example:
-
-```hbs
----
-model: googleai/gemini-2.5-flash
-data.prompt:
- trigger:
- schedule:
- cron: '0 0 * * *' # Run every day at midnight
-output:
- schema: ExampleSchema
----
-This prompt will be executed every day at midnight. Tell me something new.
-```
-
-**Important Considerations:**
-
-* The `schedule` API does not work with file-based routing. Scheduled tasks are defined and executed independently of incoming HTTP requests.
-* There can only be one trigger defined per prompt.
-* ScheduledTasks are named after the route, which can be retrieved for modification.
-
-**TaskManager API**
-
-The `TaskManager` API provides methods to manage scheduled tasks:
-
-* `single(nextRoute: string): ScheduledTask`: Retrieves a specific scheduled task by its route.
-* `all(): Map`: Returns a map of all scheduled tasks.
-* `cleanup(): void`: Stops all tasks and clears the task list.
-* `startAll(): void`: Starts all scheduled tasks.
-* `stopAll(): void`: Stops all scheduled tasks.
-
-### Using non Gemini Models
-
-dataprompt is built to work with Google AI (Gemini) models out-of-the-box, but is flexible enough to support any Genkit plugin. You can configure other models and providers by passing plugins to the `genkitPlugins` array in your configuration.
-
-[See Genkit Plugins](https://github.com/TheFireCo/genkit-plugins)
-
-Example:
-
-```js
-// dataprompt.config.js
-import { otherModelPlugin } from '';
-
-/** @type {import('dataprompt').DatapromptConfig} */
-export default {
- genkitPlugins: [
- otherModelPlugin({ /* ... */ })
- ]
-};
-```
-
-Alternatively, you can provide a fully configured Genkit instance:
-
-```js
-// dataprompt.config.js
-import { genkit } from 'genkit';
-import { otherModelPlugin } from '';
-
-/** @type {import('dataprompt').DatapromptConfig} */
-export default {
- genkit: genkit({
- plugins: [
- otherModelPlugin({ /* ... */ })
- ]
- })
-};
-```
-
-### JavaScript API - Using dataprompt in your own app
-
-You can use dataprompt's JavaScript API to integrate it into your existing applications without needing to run dataprompt as a server.
-
-1. **Create a DatapromptStore instance:**
-
- ```js
- import { dataprompt } from 'dataprompt';
-
- const store = await dataprompt({
- promptsDir: 'prompts', // Optional: Customize the prompts directory
- schemaFile: 'schema.ts' // Optional: Customize the schema file path
- });
- ```
-
- **Options:**
-
- * `promptsDir`: (string, optional) The directory where your `.prompt` files are located. Defaults to `'prompts'`.
- * `schemaFile`: (string, optional) The path to your Zod schema file. Defaults to `'schema.ts'`.
- * `genkit`: (Genkit, optional) A pre-configured Genkit instance. If not provided, dataprompt will create one with the Google AI plugin or configured `genkitPlugins`.
- * `plugins`: (DatapromptPlugin[], optional) An array of custom plugins to register.
- * `genkitPlugins`: (Plugin[], optional) An array of Genkit plugins to use.
- * `secrets`: (DatapromptSecrets, optional) An object containing API keys and other secrets.
- * `rootDir`: (string, optional) The root directory of your project.
-
-2. **Use the `generate` method:**
-
- ```js
- // Uses a request or URL to match the path but dataprompt is not running a server.
- // A URL of '/hello/david?=msg="hi" matches /prompts/hello/[user].prompt
- // and maps the query string to the request object provided to teh template
- const result = await store.generate({
- url: '/hello/david?message="hi"'
- });
- console.log(result);
- ```
-
- The `generate` method takes a URL, a Request object, or a RequestContext object as input and returns the generated output. The return type is specified with a generic.
-
- **Overloads:**
-
- * `generate