Introduction

Welcome to the Promptable documentation. This guide provides the information you need to understand and use Promptable, a local-first, node-based visual environment for building complex, AI-driven workflows.

Promptable gives you a canvas to visually map out processes, connect different types of operational nodes, and create reusable templates called Recipes. All of your creations—your Worlds, Galaxies, and Recipes—are saved directly to a folder on your local machine using the File System Access API, ensuring you always have full control and ownership of your data. While the app runs in your browser, your work stays with you.

About This Documentation

This site is meticulously organized into several key sections to help you navigate and find information efficiently:

  • Core Concepts: Explains the underlying principles and objects within our API, such as models, request structures, and response handling.
  • API Reference: Offers detailed information about each API endpoint, including required and optional parameters, expected response formats, and practical example requests and responses.
  • SDKs & Libraries: Provides information on our official and community-supported Software Development Kits (SDKs) and libraries to accelerate your development process.
  • Guides & Tutorials: Contains practical step-by-step tutorials and in-depth explanations for common tasks, advanced features, and conceptual understanding.

Quickstart Guide

This guide will walk you through the essential steps to get up and running with Promptable in minutes.

  1. Set Your Storage Location: The first time you use Promptable, you must choose a directory on your computer where all your data will be saved. Click the Set Storage Location button in the sidebar and select a folder. Promptable will create a sub-directory named Promptable to store everything. This only needs to be done once.
  2. Create Your First World: A "World" is your main workspace or canvas. In the Storage tab of the sidebar, click the + button next to the "WORLDS" heading to create and name your new World. It will load automatically.
  3. Add Nodes to the Canvas: Switch to the Builder tab in the sidebar. Click on an item like Text Node or Chat Node to add it to your World's canvas.
  4. Connect Your Nodes: Click and drag from the connection points (the gray dots) on the side of a node to another node's connection point to create a link. This defines the flow of data between them.
  5. Copy Your World: Use the Copy button in the lower right corner to copy the text representation of your World. You can then paste this directly into ChatGPT or another LLM interface for further processing or sharing.
  6. Save Your Work: Click the Save World button in the sidebar footer to save the state of your canvas to your local file system.

Installation

Instructions for installing the SDK or setting up the environment will go here.

Worlds

Documentation for Worlds goes here.

Galaxies

Galaxies in Promptable act as folders for your Worlds. Each Galaxy can contain multiple Worlds, helping you organize your projects, experiments, or workflows into logical groups. For example, you might have a Galaxy for work projects and another for personal experiments. Creating and switching between Galaxies allows you to keep related Worlds together and manage your workspace more efficiently.

Recipes

Documentation for Recipes goes here.

Flavors

Flavors are the fundamental building blocks of a Recipe Card. A Flavor is a modular, configurable, and reusable component that represents a single, specific instruction or modification within a larger Large Language Model (LLM) workflow.

Users visually combine and sequence these Flavors to construct a multi-step prompt. This sequence, once created, is stored on a Recipe Card, which can also hold associated user data, files, and other contextual information needed for the LLM task. In the UI, Flavors are represented as distinct colored cards that can be customized in detail and arranged in the LLM Instruction Mixer.

Privacy & Security: A Local-First Approach

Promptable is architected with a local-first philosophy, which puts your privacy and data ownership at the forefront. Our commitment is to ensure that you have complete control over your creations. Unlike traditional web applications, your core data does not live on our servers; it lives on your machine.

1. Data Storage: Your Data Stays on Your Device

The security and privacy of your work are determined by where it is stored. In Promptable, storage is handled in three distinct local-first ways:

  • Core Content (Worlds, Galaxies, Recipes):
    How it Works: Your primary work—including all Worlds, Galaxies, and saved Recipes—is stored directly on your computer's hard drive. The application uses the File System Access API, a modern browser feature that allows web apps to interact with your local files and folders only after you have given explicit permission. This is managed by the js/storage/fileSystemManager.js module.
    What it Means for You:
    • Complete Ownership: Your data is saved in standard JSON format in a folder you choose. You can back it up, move it, edit it, or use it with other tools as you see fit.
    • No Cloud Storage: We do not host, see, or have any access to the content of your Worlds or Recipes. It never leaves your machine unless you initiate an action that sends it to a third-party service.
    • Persistence & Control: The application can only regain access to that folder in a future session if you grant it permission again, giving you continuous control.
  • API Keys & Settings:
    How it Works: When you enter an API key for a third-party service (like OpenAI), it is saved using the browser's localStorage. This is a standard, secure storage mechanism scoped only to the Promptable origin in your browser. The js/ui/apiSettings.js file manages this process.
    What it Means for You:
    • Local Secrecy: Your API keys are stored on your device, not in a central database. We never have access to your secret keys.
    • No Server-Side Risk: Since keys are not stored on our servers, they are not vulnerable to a server-side data breach of our infrastructure.
  • Session & Configuration Data:
    How it Works: For more complex session data and caching, Promptable may use the browser's IndexedDB, as indicated by the js/storage/indexedDbService.js module. This is another form of purely local, in-browser storage.
    What it Means for You:
    • Enhanced Performance, Same Privacy: This data is used for application performance and state management during a session, but it remains entirely on your machine and is subject to the same privacy model as localStorage.

2. Data Processing: When Data Leaves Your Machine

Transparency about data flow is critical. The only time your data leaves your local machine is when you explicitly instruct the application to use a service that requires it.

  • Executing Nodes with API Calls:
    How it Works: When you run a node that needs to communicate with an external AI service (e.g., a "Chat Node" calling OpenAI), the application constructs a request. This process, handled by modules like js/utils/apiUtils.js, sends the following directly from your browser to the third-party service:
    • The prompt content you provided in the node(s).
    • Your API key (from localStorage) in the authorization header.
    What it Means for You:
    • Direct Connection: The connection is made directly between your browser and the service (e.g., OpenAI). Promptable's servers do not act as a proxy or intermediary for these requests. We do not log or store the content of your prompts or the responses.
    • Third-Party Policies Apply: Once your data is sent, it is subject to the privacy and security policies of the third-party provider you are using. We encourage you to review their policies.

3. What We Don't Do

To be perfectly clear, here is a list of things Promptable is designed not to do:

  • We do not have user accounts or a login system. Your identity is not tied to your work on any servers.
  • We do not store your Worlds, Recipes, or any other core content in the cloud.
  • We do not track the content you create or the prompts you run.
  • We do not have central servers that process or analyze your data. The application's logic runs entirely in your browser.