repository·main·Indexed 41 days ago
https://github.com/photon-hq/rapid-ai-devA toolkit for rapid AI and agent prototyping featuring reusable building blocks for terminal-first development. Version 1.0.1 provides modules like @photon-ai/rapid/cli-chat, which includes an Ink-powered terminal chat UI, the renderChatUI() controller, and the ChatUI React component for validating agent architectures, memory systems, and workflows.
Install the @photon-ai/rapid package using your preferred package manager. Rapid requires Node.js 18+ and expects typescript@^5.9.3 as a peer dependency. If you are using CommonJS, you must bundle the code or use a transpiler like ts-node/register to handle the ESM modules.
npm install @photon-ai/rapid
# or
pnpm add @photon-ai/rapid
# or
bun add @photon-ai/rapidThe @photon-ai/rapid/cli-chat module provides an Ink-powered terminal chat UI. You can render the chat surface in your CLI and use the returned controller to handle user input and send messages back to the UI. This is useful for prototyping agent interfaces directly in the terminal.
import { renderChatUI } from "@photon-ai/rapid/cli-chat";
const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
const chat = renderChatUI();
chat.sendMessage("Welcome to Rapid! Type anything and I'll echo it back.");
chat.onInput(async (prompt) => {
chat.sendMessage("Thinking...");
await delay(500);
chat.sendMessage(`Echo: ${prompt.toUpperCase()}`);
});
// Keep the Ink app alive. Press Ctrl+C to exit.
await new Promise(() => {});When using @photon-ai/rapid/cli-chat, the renderChatUI() function returns a controller object with the following methods:
renderChatUI(): Mounts the Ink application and returns the controller.chat.onInput(handler): Registers a listener for user-submitted prompts. The handler can be an async function.chat.sendMessage(content): Streams assistant messages back into the UI in real time.The renderChatUI() function initializes and renders the Chat UI using Ink. It returns a controller object that allows you to interact with the chat interface programmatically.
Through this controller, you can:
onInput(action). When a user submits a message in the UI, the provided action callback is executed with the message string.sendMessage(message). This pushes a message with the assistant role into the chat history, allowing the application to simulate or display AI responses.Note: You must call onInput or sendMessage after the UI has been rendered. If you attempt to call these methods before the controller is ready, the function will throw an error: "Chat UI is not ready to register input handlers." or "Chat UI is not ready to send messages."
import { renderChatUI } from './src/cli-chat/index';
// Initialize the UI and get the controller
const chat = renderChatUI();
// Register a listener to handle user input
chat.onInput((message: string) => {
console.log(`User said: ${message}`);
});
// Later, you can push an assistant message to the UI
// chat.sendMessage("Hello! How can I help you today?");The @photon-ai/rapid package uses subpath exports to organize its modules. Instead of importing everything from the root, you should import specific functionality from its dedicated subpaths. For example, to use the CLI Chat UI components, import from @photon-ai/rapid/cli-chat.
import { renderChatUI } from "@photon-ai/rapid/cli-chat";The ChatUI component is a React component designed for building terminal-based chat interfaces using ink. It manages the layout by combining a MessagePanel for displaying history and an InputBar for user input.
To use it, provide the following props:
messages: An array of ChatMessage objects representing the conversation history.input: The current string value of the input field.onInputChange: A callback function triggered when the user types in the input bar.onSubmit: A callback function triggered when the user submits a message.import { ChatUI, type ChatMessage } from './path-to-chat';
const messages: ChatMessage[] = [
{ role: 'user', content: 'Hello!' },
{ role: 'assistant', content: 'How can I help you today?' }
];
// Inside your Ink component:
<ChatUI
messages={messages}
input={currentInput}
onInputChange={(val) => setCurrentInput(val)}
onSubmit={(val) => handleSendMessage(val)}
/>The ChatControllerHandle defines the methods available on the controller returned by renderChatUI(). It is used to bridge the gap between the React-based UI and the external CLI logic.
| Method | Signature | Description |
|---|---|---|
onInput | (action: (input: string) => void) => void | Registers a callback that triggers whenever a user submits a message in the chat UI. |
sendMessage | (message: string) => void | Programmatically adds a message with the assistant role to the chat history. |
The ChatMessage interface defines the structure of individual messages within a conversation. Each message must specify a role (either user or assistant) and the text content.
export interface ChatMessage {
role: "user" | "assistant";
content: string;
}