diff --git a/README.md b/README.md index 15e10682..0fa3c7fc 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Perstack: The Declarative Runtime for Agentic AI +# Perstack: An Agentic AI Runtime

npm version @@ -12,142 +12,102 @@ Discord

-## Key Features - -- **`perstack` CLI**: Develop, test, and deploy Experts from the command line. -- **`create-expert` app**: Creates, tests, and refines new Experts in `perstack.toml` to your specification — powered by agentic AI. -- **`perstack.toml`**: Define and orchestrate reusable, domain-specialized agents as Experts in natural language. -- **`@perstack/runtime`**: Execute Experts programmatically. Event-sourced state with step-level checkpoints — resume, replay, and audit any execution from any point. - -## Quick Start - -Prerequisites: [Node.js 22+](https://nodejs.org/) and an [LLM provider API key](https://perstack.ai/docs/references/providers-and-models/). +**No coding. No setup. Just ask.** ```bash -npx create-expert "Create saas-developer expert that can build a SaaS product" -``` - -`create-expert` does more than scaffold a file — it: -- tests the Expert against real-world scenarios -- analyzes execution history and output to evaluate the Expert definition -- iterates on the Expert definition until behavior stabilizes -- reports capabilities and limitations of the Expert - -`perstack.toml` is created like this: -```toml -# perstack.toml - -[experts."saas-developer"] -description = "Builds a SaaS product" -instruction = """ -Build a SaaS product using Perstack. Use the tools available to you. -... (more instructions) -""" -delegates = ["@saas-developer/product-manager", "@saas-developer/developer", "(more delegates)"] - -[experts."@saas-developer/product-manager"] -description = "Manages the product roadmap" -instruction = "Manage the product roadmap and features" - -[experts."@saas-developer/developer"] -description = "Develops the product" -instruction = "Develop the product using Perstack" +npx create-expert "form an indie-game-dev team that builds high-quality 2D games for the browser" +npx perstack start indie-game-dev "Cyberpunk pixel-art beat 'em up for the browser" ``` -Run the created Expert from the CLI: - -```bash -npx perstack start saas-developer "Build an agentic CRM with Perstack" -``` +`create-expert` turns ideas into runnable agent definitions. The runtime inside `perstack` executes them. No magic — just a properly designed agentic system. -## Deployment +## Under the Hood -Use `perstack install` to generate `perstack.lock` — a pre-compiled bundle of all Expert and tool definitions. This is optional, but it lets the runtime start without spawning MCP processes, so LLM inference begins immediately. +1. **`create-expert`** generates a `perstack.toml` — agent behavior defined in plain English. It iteratively tests and refines the definition for you until it actually works. +2. **`perstack start`** executes the agents defined in `perstack.toml` and streams their activity in real time. +3. **Both run on `@perstack/runtime`** — an event-sourced, checkpointed runtime for long-running agents. Resume, replay, or diff executions across model changes whenever you want. +4. **`@perstack/base`** gives agents real-world tools (files, shell, etc.) via MCP. +5. **Complex tasks?** Agents delegate to specialist experts in parallel. -```bash -perstack install --config perstack.toml -``` -Then, you can use `perstack.lock` in docker containers, cloud functions, or any other deployment environment. The runtime automatically discovers the lockfile when it exists alongside the config. +### What `create-expert` actually generates -```dockerfile -FROM node:22-slim -RUN npm install -g perstack -COPY perstack.toml /app/perstack.toml -COPY perstack.lock /app/perstack.lock -WORKDIR /workspace -ENTRYPOINT ["perstack", "run", "--config", "/app/perstack.toml"] -``` +The indie-game-dev example above produces something like this: -Or, use it programmatically: -```typescript -import { run } from "@perstack/runtime" - -const finalCheckpoint = await run( - { - setting: { - model: "claude-sonnet-4-5", - providerConfig: { providerName: "anthropic" }, - expertKey: "saas-developer", - input: { text: "Build an agentic CRM with Perstack" }, - }, - }, - { - eventListener: (event) => { - console.log(JSON.stringify(event)) - }, - }, -) +```toml +[experts."indie-game-dev"] +description = "Indie game development team lead" +instruction = "Coordinate the team to build a high-quality 2D browser game." +delegates = ["@indie-game-dev/game-designer", "@indie-game-dev/programmer", "@indie-game-dev/artist", "@indie-game-dev/qa-tester"] + +[experts."@indie-game-dev/game-designer"] +description = "Designs game mechanics and level structure" +instruction = "Design engaging gameplay systems and level progression." + +[experts."@indie-game-dev/programmer"] +description = "Implements the game in TypeScript" +instruction = "Write clean, performant game code using HTML5 Canvas." + +[experts."@indie-game-dev/artist"] +description = "Creates pixel art assets" +instruction = "Produce consistent pixel art sprites, tilesets, and UI elements." + +[experts."@indie-game-dev/qa-tester"] +description = "Tests and finds bugs" +instruction = "Play-test the game, report bugs, and verify fixes." ``` -## Why Perstack? +Plain English. No SDK. No glue code. This file *is* the agent. -Building an agentic AI app — something like [Claude Code](https://github.com/anthropics/claude-code), [OpenHands](https://github.com/OpenHands/OpenHands), or [OpenClaw](https://github.com/openclaw/openclaw)? The agent loop, prompts, tools, and orchestration end up buried in your application code. You can't test the agent without deploying the app. You can't hand prompt tuning to domain experts without giving them access to the codebase. And when something breaks in production, you're reading raw LLM logs. +## Go Deeper -| Problem | Perstack's Approach | +| Topic | Link | | :--- | :--- | -| **Tight coupling** | Expert definitions in TOML, separate from app code, tools, and models. Deploy each independently. | -| **Broken feedback loops** | CLI to execute and analyze Experts from day one. Expert and app evolve on their own. | -| **The developer owns everything** | Domain experts tune behavior in natural language. Developers own integration. Each side ships on its own. | -| **No sustained behavior** | Event-sourced execution with step-level checkpoints. Resume, replay, and diff across model or provider changes. | -| **No real isolation** | Each Expert runs in its own context — workspace boundaries, environment sandboxing, tool whitelisting. Your platform enforces security at the infrastructure level. | +| Build your first agent | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) | +| Break complex agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) | +| Give agents real-world tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) | +| Deploy to Docker, AWS, GCP, Cloudflare | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) | +| Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) | +| Expert definitions in depth | [Making Experts](https://perstack.ai/docs/making-experts/) | +| CLI and runtime API reference | [References](https://perstack.ai/docs/references/cli/) | +| Examples: bug-finder, github-issue-bot, gmail-assistant | [examples/](./examples/) | -8 LLM providers. Switch with one config change. No vendor lock-in. - -## What to Read Next - -**Getting started:** -1. **[Build your first Expert](https://perstack.ai/guides/rapid-prototyping/)** — 5 minutes to your first Expert -2. **[Compose Experts together](https://perstack.ai/guides/taming-prompt-sprawl/)** — break monolithic prompts into collaborating Experts -3. **[Add tools via MCP](https://perstack.ai/guides/extending-with-tools/)** — give your Experts real-world capabilities +## Why Perstack? -**Going deeper:** -- [Core Concepts](https://perstack.ai/docs/understanding-perstack/concept/) — the architecture behind the runtime -- [Making Experts](https://perstack.ai/docs/making-experts/) — complete guide to Expert definitions -- [Isolation & Safety](https://perstack.ai/docs/operating-experts/isolation-by-design/) — production deployment patterns -- [CLI & API Reference](https://perstack.ai/docs/references/cli/) +You've tried building AI agents. You know how it goes. -## Examples +The prompts live in your application code. You can't test the agent without deploying the whole app. When you want to tweak behavior, it's a code change, a PR, a deploy. Domain experts who actually understand the task can't touch the prompts without a developer. And when something breaks, you're reading raw LLM logs trying to figure out which step went wrong. -| Example | Description | -| ------- | ----------- | -| [bug-finder](./examples/bug-finder/) | Codebase analyzer that finds potential bugs | -| [github-issue-bot](./examples/github-issue-bot/) | Automated GitHub issue responder that reads your codebase to answer questions | -| [gmail-assistant](./examples/gmail-assistant/) | AI-powered email assistant with Gmail integration | +Perstack separates what the agent does from how your app works. -## FAQ +| You want to... | How Perstack handles it | +| :--- | :--- | +| **Test an agent idea in 30 seconds** | `npx create-expert "..."` — running agent, no app needed. | +| **Change agent behavior** | Ask `create-expert` again. It updates, tests, and refines on your request. | +| **Let non-developers tune the agent** | Edit the definition in `perstack.toml`. The definition is plain English. | +| **Debug a failed execution** | Describe the failure to `create-expert`. It can diagnose and fix Expert definitions. | +| **Run agents safely in production** | Each agent gets its own context window. | +| **Avoid LLM vendor lock-in** | Major providers are supported. Perstack is open-source. | -### Is this an agent framework? +**Coming from other tools?** -No. Frameworks help you *build* agents in your own codebase. Perstack is just a *runtime* that *executes* them. What your application is built with is out of Perstack's scope. +| If you use... | Perstack is for you if... | +| :--- | :--- | +| **LangGraph / PydanticAI** | You don't want to build your own tool integrations, agent loop, and error-feedback plumbing just to get a real agentic system running. | +| **CrewAI / AutoGen / Google ADK** | You want runtime-level isolation per agent, full event sourcing, and no shared process. | +| **OpenAI Agents SDK** | You want true multi-provider — not Response API with a compatibility layer on top. | +| **Mastra / Vercel AI SDK** | You've hit the wall between prototype and production — job management, agent isolation, long-running lifecycles. | +| **Raw LLM SDK calls** | You're tired of building the agent loop, checkpointing, and orchestration from scratch. | -### Can Experts be used with other frameworks? +Perstack is not a framework, an orchestrator, or a UI layer. It is an **agentic AI runtime** — the execution engine that sits between your application and the LLM providers. Define agents above it. Build interfaces on top of it. -Yes. Expert definitions are TOML files, so other tools can read and interpret them. +Perstack is pre-1.0. The runtime is stable and used in production, but the API surface may evolve. [Pin your versions](https://perstack.ai/docs/references/cli/). -### Can I convert existing agents to Experts? +## Join the Community -Not directly. But you can redefine their behavior in `perstack.toml` to make them Perstack-compatible. +- **[Discord](https://discord.gg/perstack)** — Ask questions, share what you're building, get help. +- **[GitHub Issues](https://github.com/perstack-ai/perstack/issues)** — Bug reports, feature requests, ideas. +- **[@FL4T_LiN3 on X](https://x.com/FL4T_LiN3)** — Building Perstack in public. Follow for updates. ## Contributing