diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index dc2f2bd1..00000000 --- a/docs/README.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "Perstack: The Declarative Runtime for Agentic AI" ---- - -Define AI agents as **Experts** in natural language. Execute them with deterministic, event-derived tracking. Each Expert runs in its own isolated context — no shared state, no prompt bloat, full execution history. - -- [Getting Started →](./getting-started/walkthrough.md) -- [Browse Registry →](https://perstack.ai/) - -## What Perstack Solves - -Agentic app development has five structural problems. Perstack is designed to address each of them: - -| Problem | Perstack's Approach | -| :--- | :--- | -| **Tight coupling** | **A runtime** that separates Expert definitions from app code, tools, prompts, and models | -| **Broken feedback loops** | **CLI tools** to execute and analyze Experts from day one. Expert and app evolve independently. | -| **The developer owns everything** | Expert definitions in **`perstack.toml`** are written by domain experts using natural language. Developers focus on integration, not prompt engineering. | -| **No sustained behavior** | **Event-derived execution** and **step-level checkpoints** help maintain reproducible behavior, even across model or provider changes | -| **No real isolation** | **Isolation** is built into the runtime architecture — workspace boundaries, environment sandboxing, and tool whitelisting — so your platform can enforce security at the infrastructure level | - -For the full rationale, see the [root README](../README.md#why-perstack). - -## How It Works - -**1. Define** — Describe Experts in `perstack.toml` using natural language: - -```toml -[experts."fitness-assistant"] -description = "Manages fitness records and suggests training menus" -instruction = """ -Conduct interview sessions and manage records in `./fitness-log.md`. -Collaborate with `pro-trainer` for professional training menus. -""" -delegates = ["pro-trainer"] -``` - -Or generate one interactively using [`create-expert`](https://perstack.ai/), a published Expert on the Perstack registry: - -```bash -npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer" -``` - -**2. Execute** — Run from the CLI with real-time feedback: - -```bash -npx perstack start fitness-assistant "Start today's session" -``` - -**3. Integrate** — Embed into your application via the runtime API or Execution API: - -```typescript -import { run } from "@perstack/runtime" - -const checkpoint = await run({ - setting: { - model: "claude-sonnet-4-5-20250929", - providerConfig: { providerName: "anthropic" }, - expertKey: "fitness-assistant", - input: { text: "Start today's session" }, - }, -}) -``` - -## Documentation - -### Learn - -- [Getting Started](./getting-started/walkthrough.md) — create your first Expert and walk through the core workflow -- **Understanding Perstack** - - [Concept](./understanding-perstack/concept.md) — the architecture behind the runtime - - [Experts](./understanding-perstack/experts.md) — what Experts are and how they work - - [Runtime](./understanding-perstack/runtime.md) — execution model and event system - - [Sandbox Integration](./understanding-perstack/sandbox-integration.md) — infrastructure-level isolation - - [Boundary Model](./understanding-perstack/boundary-model.md) — trust boundaries between components - -### Build - -- **[Making Experts](./making-experts/best-practices.md)** — complete guide to Expert definitions - - [Examples](./making-experts/examples.md) — real-world use cases - - [Best Practices](./making-experts/best-practices.md) — design guidelines for effective Experts - - [Skills](./making-experts/skills.md) — adding MCP tools to your Experts - - [Base Skill](./making-experts/base-skill.md) — built-in tools provided by the runtime - - [Testing](./making-experts/testing.md) — strategies for testing Experts -- **[Guides](./guides/rapid-prototyping.md)** — task-oriented walkthroughs - - [Rapid Prototyping](./guides/rapid-prototyping.md) — validate ideas without writing code - - [Taming Prompt Sprawl](./guides/taming-prompt-sprawl.md) — fix bloated prompts with modular Experts - - [Extending with Tools](./guides/extending-with-tools.md) — give your Experts real-world capabilities via MCP - - [Adding AI to Your App](./guides/adding-ai-to-your-app.md) — integrate Experts into existing applications - - [Going to Production](./guides/going-to-production.md) — deploy safely with container isolation - -### Run - -- **[Using Experts](./using-experts/running-experts.md)** — run and integrate Experts - - [Running Experts](./using-experts/running-experts.md) — CLI commands and runtime API - - [Workspace](./using-experts/workspace.md) — file system layout and conventions - - [State Management](./using-experts/state-management.md) — checkpoints, pausing, resuming - - [Error Handling](./using-experts/error-handling.md) — handling failures gracefully -- **Operating Experts** — production operations - - [Isolation by Design](./operating-experts/isolation-by-design.md) — production security patterns - - [Observing](./operating-experts/observing.md) — monitoring and debugging in production - - [Skill Management](./operating-experts/skill-management.md) — managing MCP skill dependencies - - [Deployment](./operating-experts/deployment.md) — deployment strategies and infrastructure - -### Reference - -- **References** - - [CLI Reference](./references/cli.md) — all commands and options - - [perstack.toml Reference](./references/perstack-toml.md) — complete configuration spec - - [Providers and Models](./references/providers-and-models.md) — supported LLM providers - - [Events](./references/events.md) — runtime event schema -- **Contributing** - - [Roadmap](./contributing/roadmap.md) — what's planned and how to contribute - -## Community - -- [GitHub](https://github.com/perstack-ai/perstack) -- [X (@perstack_ai)](https://x.com/perstack_ai) diff --git a/docs/contributing/roadmap.md b/docs/contributing/roadmap.md deleted file mode 100644 index 6859cc29..00000000 --- a/docs/contributing/roadmap.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Roadmap" ---- - -This roadmap outlines the direction of Perstack development. Priorities may shift based on community feedback and emerging requirements. - -> [!WARNING] -> This roadmap is subject to change. Features and timelines are not commitments. - -| Feature | Status | Version | Timeline | Description | -| ------------------------------ | :----: | ------- | --------- | ------------------------------------------------- | -| **Expert definitions** | ✅ | v0.0 | - | Natural-language definitions in `perstack.toml` | -| **Runtime** | ✅ | v0.0 | - | Agent loop, checkpoint/restore, event sourcing | -| **Registry** | ✅ | v0.0 | - | Public registry with write-once versioning | -| **Skills (MCP)** | ✅ | v0.0 | - | MCP-based tool integration | -| **Multi-provider support** | ✅ | v0.0 | - | Anthropic, OpenAI, Google, Ollama | -| **CLI-based publishing** | ✅ | v0.0 | - | Publish Experts directly from CLI | -| **Dependency lockfile** | ✅ | v0.0 | - | Lock versions for reproducible builds | -| **Perstack Studio** | 📅 | - | Near-term | Visual development and debugging | -| **State transition debugging** | 📋 | - | Mid-term | Inspect and trace state transitions | -| **MFA for Expert authors** | 📋 | - | Mid-term | Multi-factor authentication for publishers | -| **Ecosystem growth** | 📋 | - | Long-term | Community Experts, best practices, integrations | -| **Advanced security** | 📋 | - | Long-term | Defense-in-depth, audit, compliance tooling | -| **exec tool sandboxing** | 📋 | - | Long-term | Restrict exec commands to workspace-only access | -| **Skill lazy initialization** | ✅ | v0.0 | - | Initialize skills on first use for faster startup | - -**Legend:** ✅ Done | 📅 Scheduled | 📋 Planning - -## Contributing - -Interested in helping shape Perstack's future? - -- **Feature requests**: [Open an issue](https://github.com/perstack-ai/perstack/issues) -- **Discussions**: [Join the conversation](https://github.com/perstack-ai/perstack/discussions) -- **Contributing code**: See [CONTRIBUTING.md](https://github.com/perstack-ai/perstack/blob/main/CONTRIBUTING.md) - -Your feedback directly influences this roadmap.