microsoft/Promptions

microsoft/Promptions

Description: Ephemeral UI for prompting

Language: TypeScript

License: MIT

Stars: 65

Forks: 15

Open issues: 7

Created: 2025-07-08T20:44:54Z

Pushed: 2026-06-22T06:58:39Z

Default branch: main

Fork: no

Archived: no

README:

Promptions - Ephemeral UI for Prompting

Ephemeral UI for prompt refinement - turn one prompt into interactive controls to steer and refine AI.

[](https://www.youtube.com/watch?v=vr3fZpkKy8Q)

Overview

Promptions is a simple, flexible dynamic prompt middleware technique for AI that uses ephemeral UI, developed by the ENCODE and Tools for Thought projects at Microsoft Research, Cambridge, UK. From a single, simple prompt, the system helps users steer the AI by suggesting parameterized choices as dynamically generated, ephemeral UI components. As users click on choices, the same output updates immediately—not just as additional chat responses. The dynamic UI can be configured per prompt.

• For more on what Promptions can do, and for responsible AI suggestions, see our [TRANSPARENCY_NOTE.md](TRANSPARENCY_NOTE.md).
• A detailed discussion of Promptions, including how it was developed and tested, can be found in our research paper "Dynamic Prompt Middleware: Contextual Prompt Refinement Controls for Comprehension Tasks."

Promptions is best suited for end-user interfaces where parameterizing prompts adds context that helps steer outputs toward user preferences, without requiring users to write or speak that context. The technique is simple yet effective, and it is easy to customize for many applications—serving developers from individual vibe coders to enterprise teams.

| Real-world use | Description | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Customer support chatbots | Users refine support queries on the fly (e.g., specify tone or detail level) and see updated answers instantly, improving resolution speed and satisfaction. | | Content creation platforms | Writers and marketers tweak style, length, or format parameters through GUI controls, iterating drafts faster while maintaining creative direction. | | Data analytics and BI dashboards | Analysts adjust filters, aggregation levels, or visualization styles via checkboxes and sliders, regenerating AI-driven reports and insights instantly. | | Educational tutoring systems | Students select difficulty, focus topics, or feedback style, prompting the AI tutor to adapt explanations and examples to individual learning needs. | | Healthcare decision-support tools | Clinicians refine symptom context, risk factors, or treatment priorities through guided options, obtaining tailored diagnostic suggestions and care pathways. | | Data annotation and curation | Promptions can parameterize labeling decisions into structured GUI inputs (e.g. sentiment sliders, style toggles), improving consistency, speed, and auditability in dataset creation. | | Interactive explainability & auditing | Promptions allows users to explore how AI outputs shift with different refinement choices, offering a lightweight way to probe bias, model boundaries, or failure modes through UI interaction. | | Human-AI co-creation experiments | Promptions enables controlled studies of creative workflows—researchers can observe how users interact with dynamic controls vs. freeform input when generating stories, resumes, or code. |

Project Structure

promptions/
├── apps/ # Frontend applications
│ ├── promptions-chat/ # Chat interface (port 3003)
│ └── promptions-image/ # Image generation interface (port 3004)
├── packages/ # Shared libraries
│ ├── promptions-llm/ # LLM utilities and integrations
│ └── promptions-ui/ # Shared React UI components
├── package.json # Root package configuration
├── nx.json # NX build system configuration
└── tsconfig.json # TypeScript configuration

Prerequisites

Before building and running this project, ensure you have:

• Node.js (v18 or higher)
• Corepack (included with Node.js v16.10+, enables automatic Yarn management)
• TypeScript (v5.0 or higher)
• An OpenAI API key _or_ an Azure OpenAI resource (API key, endpoint, and a deployment) for chat and image generation features

Setting up Corepack (Recommended)

This project uses Yarn 4.9.1 which is automatically managed via corepack. No manual Yarn installation needed!

# Enable corepack (if not already enabled)
corepack enable

# Verify corepack is working (should show yarn 4.9.1)
corepack yarn --version

> Note: Corepack is included with Node.js v16.10+ but may need to be enabled. If you're using an older Node.js version, you can install corepack separately: npm install -g corepack

Alternative: Manual Yarn Installation

If you prefer not to use corepack:

# Install Yarn globally
npm install -g yarn@4.9.1

Quick Start

1. Clone and Install Dependencies

# Clone the repository
git clone
cd promptions

# Enable corepack (if not already enabled and using corepack)
corepack enable

# Install all dependencies across the monorepo
# Corepack will automatically use the correct Yarn version (4.9.1)
yarn install

2. Build the Project

# Build all packages and applications
yarn build

3. Run the applications (and set your API key)

The apps can call either the standard OpenAI API or your own Azure OpenAI-hosted models. Configure whichever you have access to via environment variables — the same VITE_OPENAI_API_KEY variable is used in both cases (it holds either your OpenAI key or your Azure OpenAI key).

Option A — .env files (recommended for local development):

Standard OpenAI

• Create apps/promptions-chat/.env (and apps/promptions-image/.env) with:

VITE_OPENAI_API_KEY=your_openai_api_key_here
# Optional: override the chat model (defaults to gpt-5.4-nano).
# VITE_OPENAI_MODEL=gpt-5.4-nano

Azure OpenAI (using your own hosted deployment)

• Create apps/promptions-chat/.env (and apps/promptions-image/.env) with:

# Your Azure OpenAI resource key
VITE_OPENAI_API_KEY=your_azure_openai_key_here
# Your...