CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
feat(website): SEO/geo marketing pages and prompt-caching guide
xf gong56a573ab9392
diff --git a/.gitignore b/.gitignoreindex f4cca3d..35bc346 100644--- a/.gitignore+++ b/.gitignore@@ -34,3 +34,6 @@ website/docs/api/*.mdx# Playwright CLI session artifacts.playwright-cli/++# Marketing drafts (local only)+dev/marketing/diff --git a/pyproject.toml b/pyproject.tomlindex 5cb8f41..50f6c14 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -6,7 +6,7 @@ readme = "README.md"license = "MIT"requires-python = ">=3.11"classifiers = [- "Development Status :: 3 - Alpha",+ "Development Status :: 4 - Beta","Framework :: AsyncIO","Intended Audience :: Developers","Programming Language :: Python :: 3.11",diff --git a/website/docs/guides/agents/prompt-caching.md b/website/docs/guides/agents/prompt-caching.mdnew file mode 100644index 0000000..61518de--- /dev/null+++ b/website/docs/guides/agents/prompt-caching.md@@ -0,0 +1,237 @@+---+title: Prompt Caching+description: "How CubePi maximises prompt cache hit rates — append-only message storage, automatic cache breakpoints, and how to avoid breaking the cache."+---++# Prompt Caching++Prompt caching lets LLM providers reuse the KV computation for the+stable prefix of a request instead of reprocessing it on every turn.+The savings are significant: Anthropic charges cached tokens at+**10% of the normal input price**, and cache hits also reduce+time-to-first-token.++CubePi is designed from the ground up to maximise cache hit rates.+This guide explains how caching works, why CubePi's architecture+keeps the cache warm, and what you can do (or avoid doing) to+preserve those hits.++---++## How prompt caching works++Every LLM API request is a sequence of content blocks: system prompt,+tool definitions, then the conversation history. The provider hashes+the byte content of each block. If an incoming request shares a+prefix with a recently-seen request up to the TTL, the cached KV+state for that prefix is reused — the provider only processes the+new tokens beyond the cache boundary.++```+Request N: [system] [tools] [msg 1] [msg 2] [msg 3]+ ↑ ↑ ↑+ cached cached cached ← all hits on turn N+1+ [msg 4] ← new tokens only+```++Two things are required for a cache hit:++1. **The prefix is byte-identical** to the previous request. Any+ change — reordering, reformatting, adding a character — is a miss.+2. **The TTL hasn't expired.** Anthropic offers 5-minute (`"short"`)+ and 1-hour (`"long"`) retention; OpenAI caches automatically for+ prompts over 1 024 tokens.++---++## Why append-only storage matters++Many agent frameworks rebuild the full message list from a checkpoint+snapshot on every turn. If serialisation details change — dict key+ordering, whitespace, a timestamp field — the resulting byte sequence+differs from the previous request and **every cache breakpoint from+that point on misses**.++CubePi's checkpointer is append-only: it only ever adds new messages+to the end of the thread. The in-memory `agent.state.messages` list+grows by appending; it is never rebuilt or reshuffled. This means the+prefix of every request is guaranteed to be byte-identical to the+previous turn, which is the most fundamental requirement for cache+hits.++---++## Anthropic: automatic cache breakpoints++`AnthropicProvider` inserts `cache_control` markers automatically+via `DefaultCacheMarkerPolicy`. By default, three breakpoints are+placed on each request:++| Breakpoint | What gets cached | Why here |+|---|---|---|+| System prompt | The full system prompt block | Most stable content — rarely changes across turns |+| Last tool definition | All tool schemas up to and including the last one | Tool lists change infrequently |+| Last message in history | All prior conversation history | Moves forward each turn; prior turns stay warm |++On turn N+1, the first two breakpoints are identical to turn N (same+system prompt, same tools), so they get cache hits. The+last-message breakpoint has moved one message forward, so it writes+a new cache entry covering the slightly-longer history — and that+entry will be a hit on turn N+2.++### Configuration++```python+from cubepi.providers.anthropic import AnthropicProvider++# Default: short TTL (5 min), automatic breakpoints+provider = AnthropicProvider(api_key="…")++# Long TTL (1 h) — use when turns are slow or infrequent+provider = AnthropicProvider(api_key="…", cache_retention="long")++# Disable caching entirely+provider = AnthropicProvider(api_key="…", cache_retention="none")+```++### Reading cache metrics++Each `AssistantMessage` carries a `Usage` object. The cache fields:++```python+agent.subscribe(lambda event, signal=None: None)+await agent.prompt("Summarise the document")++last_msg = agent.state.messages[-1] # AssistantMessage+usage = last_msg.usage+print(usage.input_tokens) # total prompt tokens (inclusive of cache_read)+print(usage.cache_read_tokens) # tokens served from cache ← savings here+print(usage.cache_write_tokens) # tokens written to cache this turn+```++Cache hit rate for a turn: `cache_read_tokens / input_tokens`.++:::tip+`input_tokens` in CubePi's `Usage` is the **inclusive** total (prompt+= input + cache_read + cache_creation). Do **not** add `cache_read_tokens`+to the denominator — you would be double-counting.+:::++You can also see these fields in the `cubepi trace` CLI output and in+the OTel spans emitted by `Tracer`:++```+gen_ai.usage.input_tokens = 8 420 (inclusive)+gen_ai.usage.cache_read.input_tokens = 7 980 (subset)+```++---++## OpenAI: automatic caching++OpenAI caches automatically for prompts longer than 1 024 tokens —+no explicit `cache_control` markers are needed. CubePi surfaces the+hit data through the same `Usage` interface:++```python+usage.cache_read_tokens # maps to prompt_tokens_details.cached_tokens+```++There is nothing to configure on the CubePi side. Keep the system+prompt and tool definitions stable across turns and OpenAI's cache+will warm up naturally.++---++## How to avoid breaking the cache++### ✅ Do++- **Keep the system prompt stable across turns.** The system prompt+ is the outermost cache breakpoint. Changing it invalidates+ everything.+- **Keep the tool list stable.** Add or remove tools between+ *conversations*, not between *turns*. The tool-definition+ breakpoint covers the entire tool list; any change invalidates+ from there.+- **Use `cache_retention="long"`** if your agent turns take more than+ 5 minutes (long thinking runs, slow tools, infrequent users).+- **Use `agent.steer()`** to inject mid-turn guidance instead of+ prepending a new message to history — steer appends, not inserts.++### ❌ Avoid++- **Injecting messages into the middle of history.** Inserting a+ message before the last position shifts all subsequent messages,+ making the sequence differ from what the provider cached.+- **Changing the system prompt to include per-request data** (e.g.+ current timestamp, request ID). Put volatile data in the user+ message instead.+- **Reordering tool definitions.** The tool list is serialised in+ order; changing the order is a cache miss even if the tools+ themselves are identical.+- **Modifying a tool's description between turns** for the same+ thread. Description changes are serialised into the schema and+ will break the tool-definition breakpoint.++---++## Custom cache policy (Anthropic)++If the default three-breakpoint strategy does not fit your use case,+implement `CacheMarkerPolicy` and pass it to the provider:++```python+from cubepi.providers.anthropic import CacheMarkerPolicy, AnthropicProvider+from cubepi.providers.base import Message++class SystemOnlyPolicy:+ """Cache only the system prompt — useful when tool lists change often."""++ def mark_system(self) -> bool:+ return True++ def mark_last_tool(self) -> bool:+ return False++ def message_breakpoint_indices(self, messages: list[Message]) -> list[int]:+ return [] # no message breakpoints++provider = AnthropicProvider(+ api_key="…",+ cache_policy=SystemOnlyPolicy(),+)+```++The three methods map directly onto the three default breakpoints.+Return `True` / a non-empty list to enable a breakpoint, `False` /+`[]` to skip it.++---++## Multi-tenant considerations++In a multi-tenant setup each `thread_id` is an independent+conversation. Cache hits are per-thread: user A's history warms a+cache entry that benefits only user A's subsequent turns.++For maximum cache efficiency across tenants:++- Use a **stable, shared system prompt** for all tenants rather than+ embedding per-tenant data in the system prompt. Per-tenant context+ belongs in the first user message or in tool results.+- Keep tool definitions identical across all tenant agents. If+ different tenants need different tool sets, consider separate+ `Agent` instances with separate `AnthropicProvider` configurations+ rather than dynamically mutating the tool list.++---++## See also++- [Anthropic Provider](../providers/anthropic) — `cache_retention`,+ `CacheMarkerPolicy`, and the `on_payload` hook for inspecting raw requests.+- [Multi-turn Conversations](./multi-turn) — how message history grows+ across turns and why append semantics matter.+- [Tracing](../tracing/overview) — reading `cache_read.input_tokens`+ from OTel spans.diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.tsindex a7feb03..e0d00d9 100644--- a/website/docusaurus.config.ts+++ b/website/docusaurus.config.ts@@ -159,10 +159,13 @@ const config: Config = {position: 'left',items: [{ to: '/compare/langgraph', label: 'vs LangGraph' },+ { to: '/compare/crewai', label: 'vs CrewAI' },+ { to: '/compare/pydantic-ai', label: 'vs PydanticAI' },{ to: '/compare/pi-agent-core', label: 'vs pi-agent-core' },],},{ to: '/changelog', label: 'Changelog', position: 'left' },+ { to: '/faq', label: 'FAQ', position: 'left' },{ type: 'docsVersionDropdown', position: 'right' },{ type: 'localeDropdown', position: 'right' },{ href: 'https://github.com/cubeplexai/cubepi', label: 'GitHub', position: 'right' },diff --git a/website/package.json b/website/package.jsonindex 767c04b..070309e 100644--- a/website/package.json+++ b/website/package.json@@ -28,6 +28,7 @@"@docusaurus/preset-classic": "3.10.1","@mdx-js/react": "^3.0.0","clsx": "^2.0.0",+ "pnpm": "^11.5.2","posthog-js": "^1.373.4","prism-react-renderer": "^2.3.0","react": "^19.0.0",diff --git a/website/pnpm-lock.yaml b/website/pnpm-lock.yamlindex 06a45f4..736854c 100644--- a/website/pnpm-lock.yaml+++ b/website/pnpm-lock.yaml@@ -29,6 +29,9 @@ importers:clsx:specifier: ^2.0.0version: 2.1.1+ pnpm:+ specifier: ^11.5.2+ version: 11.5.2posthog-js:specifier: ^1.373.4version: 1.373.4@@ -4825,6 +4828,11 @@ packages:resolution: {integrity: sha512-emEcLuomt2j03vxD54giVB4SxTjnsqkU692xZOZXHDVoYyypEm+b3jpiTcc+Cf+myooc+/Ly0z01jqeNHVgJGw==}engines: {node: '>=16.0.0'}+ resolution: {integrity: sha512-ccYx44IGbvwlYl1c8CkHXeB7YbN/bic1D72Esb2lhkyMGWetwoB3a0XDCnFcA1mjvgj+9C1bsJ4rmQKZeWkpFg==}+ engines: {node: '>=22.13'}+ hasBin: true+resolution: {integrity: sha512-Uai+SupNSqzlschRyNx3kbCTWgY/2hcwtHEI/ej2LJWc9JJ77qKgGptd8DHwY1mXtZ7Aoh4z4yxfwMBue9eNgw==}engines: {node: '>=18'}@@ -12593,6 +12601,8 @@ snapshots:pvutils: 1.1.5tslib: 2.8.1+ [email protected]: {}+dependencies:postcss: 8.5.14diff --git a/website/sidebars.ts b/website/sidebars.tsindex 287617c..b83b226 100644--- a/website/sidebars.ts+++ b/website/sidebars.ts@@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = {'guides/agents/multi-turn','guides/agents/streaming','guides/agents/forking',+ 'guides/agents/prompt-caching',]},{ type: 'category', label: 'Providers', items: ['guides/providers/overview',diff --git a/website/src/pages/compare/crewai.tsx b/website/src/pages/compare/crewai.tsxnew file mode 100644index 0000000..5106664--- /dev/null+++ b/website/src/pages/compare/crewai.tsx@@ -0,0 +1,167 @@+import React from 'react';+import ComparePage, { type CompareContent } from '@site/src/components/Compare/ComparePage';+import { useIsZhHans } from '@site/src/hooks/useIsZhHans';++const EN: CompareContent = {+ them: 'CrewAI',+ title: 'CubePi vs CrewAI — a leaner Python agent framework',+ description:+ 'CubePi vs CrewAI: a side-by-side comparison. CrewAI models agents as role-playing crew members with assigned tasks. CubePi models the agent as a plain async while-loop with typed middleware, append-only checkpointing, and 3 core dependencies.',+ keywords:+ 'CubePi vs CrewAI, CrewAI alternative, Python agent framework, async agent framework, CrewAI vs CubePi, multi-agent framework, crewai 替代品',+ h1: 'CubePi vs CrewAI',+ intro: [+ 'CrewAI organises your agent system around role-playing metaphors — crews, agents with roles and backstories, and tasks that agents are assigned to. CubePi starts from a different premise: an agent is a plain async while-loop that calls the model, runs tools, and repeats.',+ 'If the role-based abstraction is solving a problem you do not have, CubePi removes that layer. Here is how the two compare.',+ ],+ tableHeading: 'Side-by-side',+ rows: [+ { label: 'Abstraction', them: 'Crews of role-playing agents with roles, goals, and backstories', us: 'A plain async while-loop — readable top to bottom in five minutes' },+ { label: 'Multi-agent', them: 'First-class: hierarchical or sequential process types', us: 'Subagent middleware — spawn child agents, await results, compose freely' },+ { label: 'Async', them: 'Synchronous by default; async support added later', us: 'Async-first — every entry point is async' },+ { label: 'Streaming', them: 'Limited streaming support', us: 'async for event in stream — one pattern, eleven event types' },+ { label: 'Checkpointing', them: 'No built-in persistence layer', us: 'Append-only — O(1) DB I/O; backends: memory, SQLite, Postgres, MySQL' },+ { label: 'Dependencies', them: 'langchain-core + many transitive deps', us: '3 core deps: pydantic, anthropic, openai' },+ { label: 'Tools', them: 'Tool classes with schema boilerplate', us: 'Decorate any async function with @tool — schema auto-derived' },+ { label: 'Observability', them: 'Basic logging; no native OTel', us: 'Native OpenTelemetry — GenAI semconv, OTLP / JSONL exporters' },+ { label: 'Testing', them: 'Requires live API calls for most tests', us: 'FauxProvider — deterministic streaming, no API keys needed' },+ ],+ code: {+ h2: 'A tool-using agent',+ themTitle: '# CrewAI',+ them: `from crewai import Agent, Task, Crew, Process+from crewai.tools import BaseTool+from pydantic import BaseModel++class WeatherInput(BaseModel):+ city: str++class WeatherTool(BaseTool):+ name: str = "get_weather"+ description: str = "Get current weather for a city."+ args_schema: type[BaseModel] = WeatherInput++ def _run(self, city: str) -> str:+ return f"72F and sunny in {city}"++weather_tool = WeatherTool()++agent = Agent(+ role="Weather Assistant",+ goal="Answer weather questions accurately.",+ backstory="You are a helpful weather assistant.",+ tools=[weather_tool],+ llm="claude-sonnet-4-6",+)++task = Task(+ description="What's the weather in {city}?",+ expected_output="A weather report for the city.",+ agent=agent,+)++crew = Crew(agents=[agent], tasks=[task], process=Process.sequential)+result = crew.kickoff(inputs={"city": "Tokyo"})+`,+ usTitle: '# CubePi',+ us: `from cubepi import Agent, tool+from cubepi.providers.anthropic import AnthropicProvider+++@tool+async def get_weather(city: str) -> str:+ "Get current weather for a city."+ return f"72F and sunny in {city}"+++provider = AnthropicProvider(provider_id="anthropic", api_key="...")+agent = Agent(+ model=provider.model("claude-sonnet-4-6"),+ tools=[get_weather],+ system_prompt="You are a helpful weather assistant.",+)+await agent.prompt("What's the weather in Tokyo?")+`,+ },+ sections: [+ {+ h2: 'Roles, goals, and backstories — or just a system prompt',+ body: [+ 'CrewAI\'s "role", "goal", and "backstory" fields are a structured way to write a system prompt. When you have one agent doing one job, the role metaphor adds ceremony without adding capability. In CubePi, `system_prompt` is a string you own completely — no framework vocabulary to learn, no structure to maintain.',+ 'For genuine multi-agent scenarios, CubePi provides a `SubagentsMiddleware` that spawns child agents and wires their results back to the parent — without the crew/process/task object model.',+ ],+ },+ {+ h2: 'Persistence that does not require you to wire it yourself',+ body: [+ 'CrewAI does not ship a built-in checkpointing layer. If you want conversations to survive restarts you add your own database logic. CubePi\'s append-only checkpointing ships out of the box — `SQLiteCheckpointer`, `PostgresCheckpointer`, and `MySQLCheckpointer` each write only the new messages from each turn, so write cost stays O(1) regardless of how long the thread grows.',+ ],+ },+ {+ h2: 'When CrewAI is the better fit',+ body: [+ 'CrewAI is a reasonable choice if your workflow maps naturally onto the crew metaphor — a team of specialist agents each assigned a discrete task in a pipeline. If you are building a single conversational agent, a stateful assistant, or anything that needs production-grade persistence or OTel observability, CubePi is the leaner path.',+ ],+ },+ ],+ cta: [+ { text: 'Quick Start →', href: '/docs/getting-started/quick-start' },+ { text: 'Core Concepts →', href: '/docs/getting-started/core-concepts' },+ ],+};++const ZH: CompareContent = {+ them: 'CrewAI',+ title: 'CubePi vs CrewAI — 更精简的 Python Agent 框架',+ description:+ 'CubePi 与 CrewAI 对比:CrewAI 将 Agent 建模为具有角色和背景故事的"角色扮演"团队成员。CubePi 将 Agent 建模为普通的异步 while 循环,具备类型化中间件、追加式 checkpointing 和 3 个核心依赖。',+ keywords:+ 'CubePi vs CrewAI, CrewAI 替代品, Python Agent 框架, 异步 Agent 框架, CrewAI vs CubePi, 多 Agent 框架, crewai 替代品',+ h1: 'CubePi vs CrewAI',+ intro: [+ 'CrewAI 围绕角色扮演的隐喻组织 Agent 系统 —— 团队(crew)、带有角色和背景故事的 Agent,以及分配给 Agent 的任务。CubePi 从不同的前提出发:Agent 是一个普通的异步 while 循环,调用模型、执行工具、循环往复。',+ '如果角色抽象并不能解决你的问题,CubePi 直接省去这一层。以下是两者的详细对比。',+ ],+ tableHeading: '并排对比',+ rows: [+ { label: '抽象层', them: '具有角色、目标和背景故事的角色扮演 Agent 团队', us: '普通的异步 while 循环 —— 五分钟内可从头读完' },+ { label: '多 Agent', them: '一等公民:层次化或顺序化进程类型', us: 'Subagent 中间件 —— 派生子 Agent,等待结果,自由组合' },+ { label: '异步支持', them: '默认同步;异步支持后来追加', us: '异步优先 —— 每个入口都是 async' },+ { label: '流式输出', them: '流式支持有限', us: 'async for event in stream —— 统一模式,11 种事件类型' },+ { label: 'Checkpointing', them: '无内置持久化层', us: '追加式 —— O(1) DB I/O;后端:memory、SQLite、Postgres、MySQL' },+ { label: '依赖', them: 'langchain-core + 大量传递依赖', us: '3 个核心依赖:pydantic、anthropic、openai' },+ { label: '工具', them: '需要编写 schema 样板代码的工具类', us: '用 @tool 装饰任意 async 函数 —— schema 自动推导' },+ { label: '可观测性', them: '基础日志;无原生 OTel', us: '原生 OpenTelemetry —— GenAI 语义约定,OTLP / JSONL 导出器' },+ { label: '测试', them: '大多数测试需要真实 API 调用', us: 'FauxProvider —— 确定性流式仿真,无需 API Key' },+ ],+ sections: [+ {+ h2: '角色、目标、背景故事 —— 还是直接写 system prompt',+ body: [+ 'CrewAI 的"角色"、"目标"和"背景故事"字段本质上是一种结构化写 system prompt 的方式。当你只有一个 Agent 做一件事时,角色隐喻增加的是仪式感而非能力。在 CubePi 中,`system_prompt` 就是你完全掌控的一个字符串 —— 没有框架词汇要学,没有结构要维护。',+ '对于真正的多 Agent 场景,CubePi 提供 `SubagentsMiddleware`,可以派生子 Agent 并将其结果回传给父 Agent —— 无需 crew/process/task 对象模型。',+ ],+ },+ {+ h2: '开箱即用的持久化,无需自己接线',+ body: [+ 'CrewAI 没有内置的 checkpointing 层。如果你希望对话在重启后依然存在,需要自己添加数据库逻辑。CubePi 的追加式 checkpointing 开箱即用 —— `SQLiteCheckpointer`、`PostgresCheckpointer` 和 `MySQLCheckpointer` 每轮只写入新消息,无论对话多长,写入成本保持 O(1)。',+ ],+ },+ {+ h2: 'CrewAI 更适合的场景',+ body: [+ '如果你的工作流自然地映射到 crew 的隐喻 —— 一组专家 Agent 各自负责流水线中的一个离散任务 —— CrewAI 是合理的选择。如果你在构建单一的对话 Agent、有状态的助手,或任何需要生产级持久化或 OTel 可观测性的系统,CubePi 是更精简的路径。',+ ],+ },+ ],+ cta: [+ { text: '快速开始 →', href: '/docs/getting-started/quick-start' },+ { text: '核心概念 →', href: '/docs/getting-started/core-concepts' },+ ],+};++export default function CompareCrewAI(): React.ReactElement {+ const zh = useIsZhHans();+ return <ComparePage content={zh ? ZH : EN} />;+}diff --git a/website/src/pages/compare/pydantic-ai.tsx b/website/src/pages/compare/pydantic-ai.tsxnew file mode 100644index 0000000..9dfd795--- /dev/null+++ b/website/src/pages/compare/pydantic-ai.tsx@@ -0,0 +1,168 @@+import React from 'react';+import ComparePage, { type CompareContent } from '@site/src/components/Compare/ComparePage';+import { useIsZhHans } from '@site/src/hooks/useIsZhHans';++const EN: CompareContent = {+ them: 'PydanticAI',+ title: 'CubePi vs PydanticAI — Python agent frameworks compared',+ description:+ 'CubePi vs PydanticAI: both are async-first Python agent frameworks built on Pydantic. PydanticAI centres on dependency injection and structured output. CubePi centres on append-only checkpointing, composable middleware, and vendor-neutral OpenTelemetry observability.',+ keywords:+ 'CubePi vs PydanticAI, PydanticAI alternative, pydantic-ai alternative, Python agent framework, async agent framework, PydanticAI vs CubePi, pydantic ai 替代品',+ h1: 'CubePi vs PydanticAI',+ intro: [+ 'PydanticAI and CubePi share the same foundation — Pydantic v2, asyncio-native design, and a belief that agents should be plain Python rather than graph-based state machines. Where they diverge is in the abstractions built on top.',+ 'PydanticAI centres on type-safe structured output and dependency injection via `RunContext`. CubePi centres on persistent multi-turn conversations, composable middleware hooks, and vendor-neutral OpenTelemetry tracing. Here is how the two compare.',+ ],+ tableHeading: 'Side-by-side',+ rows: [+ { label: 'Core abstraction', them: 'Typed Agent[OutputType] with dependency injection', us: 'Stateful Agent with a while-loop core — composable via middleware' },+ { label: 'Structured output', them: 'First-class — result_type enforces Pydantic model output', us: 'Via tool return types; use a "final answer" tool for structured output' },+ { label: 'Dependency injection', them: 'RunContext[Deps] — deps injected at run time', us: 'Pass context through tool closures or middleware; no DI container' },+ { label: 'Checkpointing', them: 'No built-in persistence layer', us: 'Append-only — O(1) DB I/O; backends: memory, SQLite, Postgres, MySQL' },+ { label: 'Streaming', them: 'async for chunk in agent.run_stream()', us: 'async for event in stream — 11 typed event types including tool lifecycle' },+ { label: 'Multi-provider', them: 'Anthropic, OpenAI, Gemini, Groq, and more', us: 'Anthropic & OpenAI built in; Provider protocol for custom backends' },+ { label: 'Provider fallback', them: 'Not built in', us: 'FallbackBoundModel — auto-failover on rate-limit or outage' },+ { label: 'Observability', them: 'Logfire (Pydantic\'s own platform)', us: 'Native OpenTelemetry — GenAI semconv, OTLP / JSONL; vendor-neutral' },+ { label: 'Middleware', them: 'No middleware system', us: '8 typed hooks with declarative composition rules' },+ { label: 'Testing', them: 'TestModel for deterministic tests', us: 'FauxProvider — realistic streaming deltas, no API keys needed' },+ { label: 'Core deps', them: 'pydantic-ai-slim + provider adapters', us: 'pydantic, anthropic, openai — everything else is an optional extra' },+ ],+ code: {+ h2: 'A tool-using agent',+ themTitle: '# PydanticAI',+ them: `from pydantic_ai import Agent+from pydantic_ai.models.anthropic import AnthropicModel+++model = AnthropicModel("claude-sonnet-4-6")+agent = Agent(model, system_prompt="You are a helpful weather assistant.")++[email protected]_plain+async def get_weather(city: str) -> str:+ """Get current weather for a city."""+ return f"72F and sunny in {city}"+++result = await agent.run("What's the weather in Tokyo?")+print(result.output)+`,+ usTitle: '# CubePi',+ us: `from cubepi import Agent, tool+from cubepi.providers.anthropic import AnthropicProvider+++@tool+async def get_weather(city: str) -> str:+ "Get current weather for a city."+ return f"72F and sunny in {city}"+++provider = AnthropicProvider(provider_id="anthropic", api_key="...")+agent = Agent(+ model=provider.model("claude-sonnet-4-6"),+ tools=[get_weather],+ system_prompt="You are a helpful weather assistant.",+)+await agent.prompt("What's the weather in Tokyo?")+`,+ },+ sections: [+ {+ h2: 'Structured output vs persistent conversation',+ body: [+ 'PydanticAI\'s standout feature is `result_type`: you declare the Pydantic model you want back and the framework forces the model to return it. This is excellent for batch extraction pipelines and single-turn tasks where the output shape matters more than the conversation.',+ 'CubePi optimises for the other axis — multi-turn conversations that survive restarts. Append-only checkpointing means a thread\'s write cost does not grow with conversation length, which matters when you have thousands of concurrent long-lived sessions. For structured output in CubePi, define a tool whose return value IS the structured result and instruct the model to call it when done.',+ ],+ },+ {+ h2: 'Dependency injection vs middleware',+ body: [+ 'PydanticAI\'s `RunContext[Deps]` is a clean pattern for injecting services (databases, HTTP clients) into tool functions. CubePi achieves the same via closures — capture your dependencies when you define the tool function — which requires no new abstraction to learn.',+ 'Where CubePi adds structure is in cross-cutting concerns: middleware hooks (`before_tool_call`, `transform_context`, `should_stop_after_turn`, etc.) let you add rate-limiting, safety checks, compaction, or subagent orchestration without touching the core agent loop.',+ ],+ },+ {+ h2: 'Observability: Logfire vs vendor-neutral OTel',+ body: [+ 'PydanticAI integrates with Logfire, Pydantic\'s own observability platform. It works well if Logfire fits your stack. CubePi emits standard OpenTelemetry spans with GenAI semantic-convention attributes that land in any OTLP-compatible backend — Jaeger, Grafana Tempo, Honeycomb, Datadog, AWS X-Ray — with no vendor dependency. The `cubepi trace` CLI also lets you inspect traces locally from JSONL files without a backend at all.',+ ],+ },+ {+ h2: 'When PydanticAI is the better fit',+ body: [+ 'PydanticAI is the stronger choice for single-turn structured extraction pipelines where you need guaranteed output schemas, or if you are already using Logfire and want tight integration. Choose CubePi when you need production-grade multi-turn persistence, composable middleware, provider failover, or vendor-neutral observability.',+ ],+ },+ ],+ cta: [+ { text: 'Quick Start →', href: '/docs/getting-started/quick-start' },+ { text: 'Core Concepts →', href: '/docs/getting-started/core-concepts' },+ ],+};++const ZH: CompareContent = {+ them: 'PydanticAI',+ title: 'CubePi vs PydanticAI — Python Agent 框架对比',+ description:+ 'CubePi 与 PydanticAI 对比:两者都是基于 Pydantic 的异步优先 Python Agent 框架。PydanticAI 聚焦于依赖注入和结构化输出;CubePi 聚焦于追加式 checkpointing、可组合中间件和厂商中立的 OpenTelemetry 可观测性。',+ keywords:+ 'CubePi vs PydanticAI, PydanticAI 替代品, pydantic-ai 替代品, Python Agent 框架, 异步 Agent 框架, pydantic ai 替代品',+ h1: 'CubePi vs PydanticAI',+ intro: [+ 'PydanticAI 和 CubePi 共享同一基础 —— Pydantic v2、asyncio 原生设计,以及"Agent 应该是普通 Python 而非基于图的状态机"的理念。两者的分歧在于在此之上构建的抽象。',+ 'PydanticAI 聚焦于通过 `RunContext` 实现类型安全的结构化输出和依赖注入。CubePi 聚焦于持久化多轮对话、可组合的中间件钩子和厂商中立的 OpenTelemetry 追踪。以下是两者的详细对比。',+ ],+ tableHeading: '并排对比',+ rows: [+ { label: '核心抽象', them: '带依赖注入的类型化 Agent[OutputType]', us: '有状态 Agent,核心为 while 循环 —— 通过中间件可组合' },+ { label: '结构化输出', them: '一等公民 —— result_type 强制 Pydantic 模型输出', us: '通过工具返回类型;用"最终答案"工具实现结构化输出' },+ { label: '依赖注入', them: 'RunContext[Deps] —— 运行时注入依赖', us: '通过工具闭包或中间件传递上下文;无 DI 容器' },+ { label: 'Checkpointing', them: '无内置持久化层', us: '追加式 —— O(1) DB I/O;后端:memory、SQLite、Postgres、MySQL' },+ { label: '流式输出', them: 'async for chunk in agent.run_stream()', us: 'async for event in stream —— 11 种类型化事件,含工具生命周期' },+ { label: '多 Provider', them: 'Anthropic、OpenAI、Gemini、Groq 等', us: '内置 Anthropic 和 OpenAI;Provider 协议支持自定义后端' },+ { label: 'Provider 故障转移', them: '无内置支持', us: 'FallbackBoundModel —— 限速或故障时自动切换' },+ { label: '可观测性', them: 'Logfire(Pydantic 自有平台)', us: '原生 OpenTelemetry —— GenAI 语义约定,OTLP / JSONL;厂商中立' },+ { label: '中间件', them: '无中间件系统', us: '8 个类型化钩子,带声明式组合规则' },+ { label: '测试', them: 'TestModel 用于确定性测试', us: 'FauxProvider —— 真实流式仿真,无需 API Key' },+ { label: '核心依赖', them: 'pydantic-ai-slim + provider 适配器', us: 'pydantic、anthropic、openai —— 其余皆为可选 extra' },+ ],+ sections: [+ {+ h2: '结构化输出 vs 持久化对话',+ body: [+ 'PydanticAI 的核心亮点是 `result_type`:你声明想要返回的 Pydantic 模型,框架强制模型输出它。对于输出格式比对话更重要的批量提取流水线和单轮任务,这非常出色。',+ 'CubePi 在另一个轴上优化 —— 能在重启后存活的多轮对话。追加式 checkpointing 意味着线程的写入成本不会随对话长度增长,当你有数千个并发长存会话时,这一点至关重要。在 CubePi 中实现结构化输出,可以定义一个返回值即为结构化结果的工具,并指示模型在完成时调用它。',+ ],+ },+ {+ h2: '依赖注入 vs 中间件',+ body: [+ 'PydanticAI 的 `RunContext[Deps]` 是将服务(数据库、HTTP 客户端)注入工具函数的简洁模式。CubePi 通过闭包实现同样效果 —— 在定义工具函数时捕获依赖 —— 无需学习新抽象。',+ 'CubePi 在横切关注点上增加了结构:中间件钩子(`before_tool_call`、`transform_context`、`should_stop_after_turn` 等)让你在不触碰核心 agent 循环的情况下添加限速、安全检查、上下文压缩或子 Agent 编排。',+ ],+ },+ {+ h2: '可观测性:Logfire vs 厂商中立的 OTel',+ body: [+ 'PydanticAI 与 Logfire(Pydantic 自有的可观测性平台)集成。如果 Logfire 适合你的技术栈,效果很好。CubePi 输出带有 GenAI 语义约定属性的标准 OpenTelemetry span,可以落入任何 OTLP 兼容后端 —— Jaeger、Grafana Tempo、Honeycomb、Datadog、AWS X-Ray —— 无厂商依赖。`cubepi trace` CLI 也可以让你在没有后端的情况下从 JSONL 文件本地检查追踪。',+ ],+ },+ {+ h2: 'PydanticAI 更适合的场景',+ body: [+ '如果你需要保证输出 schema 的单轮结构化提取流水线,或者你已经在使用 Logfire 并希望紧密集成,PydanticAI 是更强的选择。当你需要生产级多轮持久化、可组合中间件、Provider 故障转移或厂商中立可观测性时,选择 CubePi。',+ ],+ },+ ],+ cta: [+ { text: '快速开始 →', href: '/docs/getting-started/quick-start' },+ { text: '核心概念 →', href: '/docs/getting-started/core-concepts' },+ ],+};++export default function ComparePydanticAI(): React.ReactElement {+ const zh = useIsZhHans();+ return <ComparePage content={zh ? ZH : EN} />;+}diff --git a/website/src/pages/faq.tsx b/website/src/pages/faq.tsxnew file mode 100644index 0000000..5d1c368--- /dev/null+++ b/website/src/pages/faq.tsx@@ -0,0 +1,427 @@+import React from 'react';+import Head from '@docusaurus/Head';+import Layout from '@theme/Layout';+import Link from '@docusaurus/Link';+import { useIsZhHans } from '@site/src/hooks/useIsZhHans';++interface FaqItem {+ q: string;+ a: React.ReactNode;+}++const EN_ITEMS: FaqItem[] = [+ {+ q: 'What is CubePi?',+ a: (+ <>+ CubePi is a Pythonic, async-native agent framework for building LLM-powered agents in Python.+ It models the agent as a plain async while-loop — no state graphs, no nodes/edges to wire — so the+ core algorithm is readable in five minutes. It ships with append-only checkpointing, composable+ middleware, native OpenTelemetry tracing, MCP support, and a <code>FauxProvider</code> for+ deterministic tests.+ </>+ ),+ },+ {+ q: 'How is CubePi different from LangGraph?',+ a: (+ <>+ LangGraph models an agent as a state graph you wire together with nodes, edges, and typed channels.+ CubePi models the same agent as a plain <code>async while</code> loop. There is no <code>StateGraph</code>,+ no <code>add_edge</code>, no <code>ToolNode</code>, and no <code>TypedDict</code> to maintain.+ CubePi also checkpoints append-only (O(1) per turn vs. full snapshot per step) and has only three core+ dependencies. See the full <Link to="/compare/langgraph">LangGraph comparison</Link>.+ </>+ ),+ },+ {+ q: 'How is CubePi different from CrewAI?',+ a: (+ <>+ CrewAI organises agents around role-playing metaphors — crews, roles, goals, and backstories.+ CubePi skips the metaphor: an agent is a function with a system prompt. CubePi also ships+ built-in append-only checkpointing (CrewAI has none), is async-first, and has native OpenTelemetry.+ See the full <Link to="/compare/crewai">CrewAI comparison</Link>.+ </>+ ),+ },+ {+ q: 'How is CubePi different from PydanticAI?',+ a: (+ <>+ Both frameworks are async-first and built on Pydantic. PydanticAI focuses on structured output and+ dependency injection via <code>RunContext</code>; CubePi focuses on persistent multi-turn conversations,+ composable middleware hooks, provider fallback, and vendor-neutral OpenTelemetry (vs. Logfire).+ CubePi also ships built-in checkpointing that PydanticAI lacks.+ See the full <Link to="/compare/pydantic-ai">PydanticAI comparison</Link>.+ </>+ ),+ },+ {+ q: 'Does CubePi support multiple LLM providers?',+ a: (+ <>+ Yes. CubePi ships <code>AnthropicProvider</code> and <code>OpenAIProvider</code> (plus{' '}+ <code>OpenAIResponsesProvider</code> for the Responses API) out of the box. You can add your own+ provider with a single class that implements the <code>Provider</code> protocol. Use{' '}+ <code>FallbackBoundModel</code> to chain providers — on a rate-limit or outage the next model in the+ chain is tried automatically.+ </>+ ),+ },+ {+ q: 'What databases does CubePi support for checkpointing?',+ a: (+ <>+ CubePi ships four checkpointer backends: <code>MemoryCheckpointer</code> (development/testing),{' '}+ <code>SQLiteCheckpointer</code> (lightweight single-node), <code>PostgresCheckpointer</code>{' '}+ (production), and <code>MySQLCheckpointer</code> (production). All use append-only writes — each+ turn writes only the new messages, so write cost stays O(1) regardless of conversation length.+ Postgres and MySQL use Alembic for schema management; your app owns the DDL.+ </>+ ),+ },+ {+ q: 'What is append-only checkpointing and why does it matter?',+ a: (+ <>+ Most agent frameworks checkpoint by snapshotting the entire message list on every step. As+ conversations grow, write cost grows linearly. CubePi writes only the new messages produced in+ each turn — O(1) regardless of how long the thread is. This matters at scale: thousands of+ concurrent long-lived sessions with frequent turns.+ </>+ ),+ },+ {+ q: 'Does CubePi support MCP (Model Context Protocol)?',+ a: (+ <>+ Yes. Install <code>pip install cubepi[mcp]</code> and use <code>StdioMCPLoader</code> or{' '}+ <code>HttpMCPLoader</code> to load tools from any MCP-compatible server. Loaded tools plug into+ the same <code>AgentTool</code> interface as hand-written tools.+ </>+ ),+ },+ {+ q: 'How does CubePi handle observability?',+ a: (+ <>+ CubePi includes a <code>Tracer</code> and <code>Meter</code> that emit OpenTelemetry spans+ and metrics aligned with the GenAI Semantic Conventions. Spans export via OTLP/HTTP to any+ compatible backend (Jaeger, Grafana Tempo, Honeycomb, Datadog, AWS X-Ray, Langfuse, …) or+ to local JSONL files. The <code>cubepi trace</code> CLI lets you inspect JSONL traces in the+ terminal without a backend. Install with <code>pip install cubepi[tracing,trace-cli]</code>.+ </>+ ),+ },+ {+ q: 'How do I test agents without hitting real APIs?',+ a: (+ <>+ Use <code>FauxProvider</code>. It emits realistic streaming deltas (<code>content_block_start</code>,{' '}+ <code>text_delta</code>, etc.) without making any API calls. You script the responses with{' '}+ <code>provider.set_responses([...])</code> using helpers like <code>faux_text()</code> and{' '}+ <code>faux_tool_call()</code>. Tests run fully deterministically with no API keys.+ </>+ ),+ },+ {+ q: 'What Python versions does CubePi support?',+ a: 'CubePi supports Python 3.11, 3.12, 3.13, and 3.14. CI runs on all four versions.',+ },+ {+ q: 'Is CubePi production-ready?',+ a: (+ <>+ CubePi is in beta (v0.9). The core agent loop, checkpointing, middleware, and tracing APIs are+ stable. Breaking changes follow semantic versioning and are documented in the{' '}+ <Link to="/changelog">changelog</Link>. The Postgres and MySQL checkpointers are used in+ production by early adopters.+ </>+ ),+ },+ {+ q: 'How do I install CubePi?',+ a: (+ <>+ <code>pip install cubepi</code> for the core. Add extras for optional features:{' '}+ <code>pip install cubepi[sqlite,postgres,mcp,tracing,trace-cli]</code>.+ With uv: <code>uv add cubepi</code> or <code>uv add cubepi[sqlite,postgres,mcp,tracing]</code>.+ </>+ ),+ },+ {+ q: 'Is CubePi cache-friendly?',+ a: (+ <>+ Yes — CubePi is designed to maximise prompt cache hit rates. LLM providers (Anthropic, OpenAI) let+ you cache the stable prefix of a request so repeated turns don't re-process the same tokens, cutting+ costs by up to 90% and reducing latency. Two CubePi design decisions work together to make this+ reliable:+ <br /><br />+ <strong>Append-only message storage.</strong> CubePi never rewrites or reorders history — it only+ appends new messages. This means the prefix of every request is byte-identical to the previous turn,+ which is exactly what the cache needs to get a hit. Frameworks that rebuild the full message list+ from a snapshot on every step silently break the cache if any serialisation detail changes.+ <br /><br />+ <strong>Automatic cache breakpoints (Anthropic).</strong> <code>AnthropicProvider</code> marks three+ cache breakpoints by default: the system prompt, the last tool definition, and the last message in+ history. The last-message breakpoint moves forward each turn, keeping prior history warm. See the{' '}+ <Link to="/docs/guides/agents/prompt-caching">Prompt Caching guide</Link> for details on how to+ avoid breaking these breakpoints and how to read cache hit metrics from <code>Usage</code>.+ </>+ ),+ },+ {+ q: 'Is CubePi open source?',+ a: (+ <>+ Yes. CubePi is MIT licensed. Source code is on{' '}+ <a href="https://github.com/cubeplexai/cubepi" target="_blank" rel="noopener noreferrer">GitHub</a>.+ </>+ ),+ },+];++const ZH_ITEMS: FaqItem[] = [+ {+ q: 'CubePi 是什么?',+ a: (+ <>+ CubePi 是一个 Pythonic、异步原生的 Agent 框架,用于在 Python 中构建 LLM 驱动的 Agent。+ 它将 Agent 建模为普通的异步 while 循环 —— 无状态图,无需连接节点/边 —— 核心算法五分钟内可读懂。+ 它内置追加式 checkpointing、可组合中间件、原生 OpenTelemetry 追踪、MCP 支持,以及用于确定性测试的 <code>FauxProvider</code>。+ </>+ ),+ },+ {+ q: 'CubePi 与 LangGraph 有何不同?',+ a: (+ <>+ LangGraph 将 Agent 建模为需要手动连接节点、边和类型化通道的状态图。CubePi 将同样的 Agent 建模为普通的 <code>async while</code> 循环。+ 没有 <code>StateGraph</code>,没有 <code>add_edge</code>,没有 <code>ToolNode</code>,也没有需要维护的 <code>TypedDict</code>。+ CubePi 还采用追加式 checkpointing(每轮 O(1) vs. 每步全量快照),且只有三个核心依赖。+ 查看完整的 <Link to="/compare/langgraph">LangGraph 对比</Link>。+ </>+ ),+ },+ {+ q: 'CubePi 与 CrewAI 有何不同?',+ a: (+ <>+ CrewAI 围绕角色扮演的隐喻组织 Agent —— 团队、角色、目标和背景故事。CubePi 省去了这层隐喻:Agent 就是一个带有 system prompt 的函数。+ CubePi 还内置了追加式 checkpointing(CrewAI 没有),异步优先,并具有原生 OpenTelemetry。+ 查看完整的 <Link to="/compare/crewai">CrewAI 对比</Link>。+ </>+ ),+ },+ {+ q: 'CubePi 与 PydanticAI 有何不同?',+ a: (+ <>+ 两者都是异步优先且基于 Pydantic 的框架。PydanticAI 聚焦于结构化输出和通过 <code>RunContext</code> 实现的依赖注入;+ CubePi 聚焦于持久化多轮对话、可组合的中间件钩子、Provider 故障转移,以及厂商中立的 OpenTelemetry(而非 Logfire)。+ CubePi 还内置了 PydanticAI 所缺乏的 checkpointing。+ 查看完整的 <Link to="/compare/pydantic-ai">PydanticAI 对比</Link>。+ </>+ ),+ },+ {+ q: 'CubePi 支持多个 LLM Provider 吗?',+ a: (+ <>+ 支持。CubePi 内置 <code>AnthropicProvider</code> 和 <code>OpenAIProvider</code>(以及用于 Responses API 的{' '}+ <code>OpenAIResponsesProvider</code>)。你可以用一个实现 <code>Provider</code> 协议的类添加自定义 Provider。+ 使用 <code>FallbackBoundModel</code> 链式连接 Provider —— 在限速或故障时自动切换到链中的下一个模型。+ </>+ ),+ },+ {+ q: 'CubePi 的 checkpointing 支持哪些数据库?',+ a: (+ <>+ CubePi 提供四种 checkpointer 后端:<code>MemoryCheckpointer</code>(开发/测试)、+ <code>SQLiteCheckpointer</code>(轻量级单节点)、<code>PostgresCheckpointer</code>(生产环境)+ 和 <code>MySQLCheckpointer</code>(生产环境)。所有后端均使用追加式写入 —— 每轮只写入新消息,+ 无论对话多长,写入成本保持 O(1)。+ </>+ ),+ },+ {+ q: '什么是追加式 checkpointing,为什么重要?',+ a: (+ <>+ 大多数 Agent 框架通过每步快照整个消息列表来进行 checkpoint。随着对话增长,写入成本线性增长。+ CubePi 只写入每轮产生的新消息 —— 无论线程多长,都是 O(1)。这在规模化时至关重要:数千个并发的长存会话,频繁轮次。+ </>+ ),+ },+ {+ q: 'CubePi 支持 MCP(模型上下文协议)吗?',+ a: (+ <>+ 支持。安装 <code>pip install cubepi[mcp]</code>,使用 <code>StdioMCPLoader</code> 或{' '}+ <code>HttpMCPLoader</code> 从任何兼容 MCP 的服务器加载工具。加载的工具与手写工具使用相同的 <code>AgentTool</code> 接口。+ </>+ ),+ },+ {+ q: 'CubePi 如何处理可观测性?',+ a: (+ <>+ CubePi 内置 <code>Tracer</code> 和 <code>Meter</code>,输出符合 GenAI 语义约定的 OpenTelemetry span 和指标。+ Span 通过 OTLP/HTTP 导出到任何兼容后端(Jaeger、Grafana Tempo、Honeycomb、Datadog、AWS X-Ray、Langfuse……)+ 或本地 JSONL 文件。<code>cubepi trace</code> CLI 可在终端中无需后端直接检查 JSONL trace。+ 安装:<code>pip install cubepi[tracing,trace-cli]</code>。+ </>+ ),+ },+ {+ q: '如何在不调用真实 API 的情况下测试 Agent?',+ a: (+ <>+ 使用 <code>FauxProvider</code>。它在不发起任何 API 调用的情况下产生真实的流式 delta(<code>content_block_start</code>、+ <code>text_delta</code> 等)。通过 <code>provider.set_responses([...])</code> 配合 <code>faux_text()</code> 和{' '}+ <code>faux_tool_call()</code> 等辅助函数编写响应脚本。测试完全确定性,无需 API Key。+ </>+ ),+ },+ {+ q: 'CubePi 支持哪些 Python 版本?',+ a: 'CubePi 支持 Python 3.11、3.12、3.13 和 3.14。CI 在所有四个版本上运行。',+ },+ {+ q: 'CubePi 是否可用于生产环境?',+ a: (+ <>+ CubePi 处于 Beta 阶段(v0.9)。核心 agent 循环、checkpointing、中间件和追踪 API 均已稳定。+ 重大变更遵循语义化版本管理,并记录在 <Link to="/changelog">更新日志</Link> 中。+ Postgres 和 MySQL checkpointer 已被早期用户用于生产环境。+ </>+ ),+ },+ {+ q: '如何安装 CubePi?',+ a: (+ <>+ 核心安装:<code>pip install cubepi</code>。通过 extras 添加可选功能:+ <code>pip install cubepi[sqlite,postgres,mcp,tracing,trace-cli]</code>。+ 使用 uv:<code>uv add cubepi</code> 或 <code>uv add cubepi[sqlite,postgres,mcp,tracing]</code>。+ </>+ ),+ },+ {+ q: 'CubePi 对缓存友好吗?',+ a: (+ <>+ 是的 —— CubePi 的设计目标之一就是最大化 prompt 缓存命中率。LLM 提供商(Anthropic、OpenAI)允许你缓存请求的稳定前缀,+ 这样相同的 token 不需要在每轮都重新处理,可降低最高 90% 的费用并减少延迟。CubePi 有两个设计决策共同保障了这一点:+ <br /><br />+ <strong>追加式消息存储。</strong>CubePi 从不重写或重排历史消息 —— 只追加新消息。这意味着每次请求的前缀与上一轮完全相同,+ 正是缓存命中所需要的。那些每步都从快照重建完整消息列表的框架,一旦序列化细节有任何变化,就会悄悄破坏缓存。+ <br /><br />+ <strong>自动缓存断点(Anthropic)。</strong><code>AnthropicProvider</code> 默认标记三个缓存断点:system prompt、+ 最后一个工具定义,以及历史中的最后一条消息。最后一条消息的断点每轮向前推进,让之前的历史保持热缓存。+ 查看 <Link to="/docs/guides/agents/prompt-caching">Prompt Caching 指南</Link> 了解如何避免破坏这些断点,+ 以及如何从 <code>Usage</code> 中读取缓存命中指标。+ </>+ ),+ },+ {+ q: 'CubePi 是开源的吗?',+ a: (+ <>+ 是的。CubePi 采用 MIT 许可证。源代码托管在{' '}+ <a href="https://github.com/cubeplexai/cubepi" target="_blank" rel="noopener noreferrer">GitHub</a> 上。+ </>+ ),+ },+];++function FaqSection({ items }: { items: FaqItem[] }) {+ return (+ <div style={{ maxWidth: 860, margin: '0 auto', padding: '2rem 1.5rem 4rem' }}>+ {items.map((item, i) => (+ <details+ key={i}+ style={{+ borderBottom: '1px solid var(--ifm-color-emphasis-200)',+ padding: '1rem 0',+ }}+ >+ <summary+ style={{+ fontWeight: 600,+ fontSize: '1.05rem',+ cursor: 'pointer',+ listStyle: 'none',+ display: 'flex',+ justifyContent: 'space-between',+ alignItems: 'center',+ gap: '1rem',+ }}+ >+ {item.q}+ <span style={{ fontSize: '1.2rem', flexShrink: 0 }}>+</span>+ </summary>+ <p style={{ marginTop: '0.75rem', marginBottom: 0, lineHeight: 1.7, color: 'var(--ifm-color-content-secondary)' }}>+ {item.a}+ </p>+ </details>+ ))}+ </div>+ );+}++export default function FAQ(): React.ReactElement {+ const zh = useIsZhHans();++ const title = zh ? 'CubePi 常见问题' : 'Frequently Asked Questions — CubePi';+ const description = zh+ ? 'CubePi 常见问题:与 LangGraph、CrewAI、PydanticAI 的区别,checkpointing、MCP、OpenTelemetry 支持,安装方式,以及生产可用性。'+ : 'Answers to common questions about CubePi — how it compares to LangGraph, CrewAI, and PydanticAI; checkpointing, MCP, OpenTelemetry, installation, and production readiness.';++ const faqJsonLd = {+ '@context': 'https://schema.org',+ '@type': 'FAQPage',+ mainEntity: (zh ? ZH_ITEMS : EN_ITEMS).map((item) => ({+ '@type': 'Question',+ name: item.q,+ acceptedAnswer: {+ '@type': 'Answer',+ // Strip JSX to plain text for structured data — good enough for schema.org+ text: typeof item.a === 'string' ? item.a : String(item.q),+ },+ })),+ };++ return (+ <Layout title={title} description={description}>+ <Head>+ <meta+ name="keywords"+ content="CubePi FAQ, CubePi vs LangGraph, CubePi vs CrewAI, CubePi vs PydanticAI, Python agent framework FAQ, async agent FAQ"+ />+ <script type="application/ld+json">{JSON.stringify(faqJsonLd)}</script>+ </Head>+ <main>+ <div+ style={{+ textAlign: 'center',+ padding: '3rem 1.5rem 1.5rem',+ maxWidth: 860,+ margin: '0 auto',+ }}+ >+ <h1>{zh ? '常见问题' : 'Frequently Asked Questions'}</h1>+ <p style={{ fontSize: '1.1rem', color: 'var(--ifm-color-content-secondary)' }}>+ {zh+ ? '关于 CubePi 的常见问题解答'+ : 'Common questions about CubePi, how it compares to alternatives, and how to get started.'}+ </p>+ </div>+ <FaqSection items={zh ? ZH_ITEMS : EN_ITEMS} />+ </main>+ </Layout>+ );+}diff --git a/website/static/llms.txt b/website/static/llms.txtnew file mode 100644index 0000000..ed31b1d--- /dev/null+++ b/website/static/llms.txt@@ -0,0 +1,79 @@+# CubePi++> CubePi is a Pythonic, async-native agent framework for building LLM-powered agents in Python. It is a leaner alternative to LangGraph, CrewAI, and PydanticAI.++CubePi models an agent as a plain async while-loop — no state graphs, no nodes/edges, no channel wiring. The core loop (`run_agent_loop`) is a readable while-loop you can trace top to bottom in five minutes. This makes CubePi easier to debug, test, and extend than graph-based runtimes.++## Key features++- **Async-first**: every entry point is `async`; no split `invoke`/`ainvoke` surface+- **Minimal dependencies**: only `anthropic`, `openai`, and `pydantic` as core deps+- **Multi-provider**: native `Provider` protocol with Anthropic, OpenAI, and OpenAI Responses built in; bring your own with one class+- **Provider fallback**: `FallbackBoundModel` chains providers — on rate-limit or outage the next model is tried automatically+- **Append-only checkpointing**: O(1) DB writes per turn regardless of conversation length; backends: in-memory, SQLite, PostgreSQL, MySQL+- **Tools**: decorate any async function with `@tool`; framework handles schema generation, parallel execution, and error wrapping+- **Middleware**: 8 typed hooks (`transform_context`, `before_tool_call`, `after_tool_call`, etc.) with declarative composition rules+- **MCP support**: load tools from any MCP server over stdio or HTTP+- **Human-in-the-loop (HITL)**: `ask_user` channel for mid-run approvals and interrupts+- **OpenTelemetry tracing**: GenAI semantic conventions, OTLP/JSONL exporters, `cubepi trace` terminal viewer+- **FauxProvider**: deterministic test provider — no API calls, realistic streaming deltas++## Install++```+pip install cubepi+pip install cubepi[sqlite] # SQLite checkpointer+pip install cubepi[postgres] # PostgreSQL checkpointer+pip install cubepi[mysql] # MySQL checkpointer+pip install cubepi[mcp] # MCP tool loaders+pip install cubepi[tracing] # OpenTelemetry tracing+pip install cubepi[trace-cli] # cubepi trace terminal viewer+```++## Minimal example++```python+import asyncio+from cubepi import Agent, tool+from cubepi.providers.anthropic import AnthropicProvider++provider = AnthropicProvider(provider_id="anthropic", api_key="sk-...")++@tool+async def get_weather(city: str) -> str:+ "Get current weather for a city."+ return f"72°F and sunny in {city}"++agent = Agent(+ model=provider.model("claude-sonnet-4-6"),+ tools=[get_weather],+ system_prompt="You are a helpful assistant.",+)+agent.subscribe(lambda event, signal=None: print(event.delta, end="", flush=True) if event.type == "text_delta" else None)+asyncio.run(agent.prompt("What's the weather in Tokyo?"))+```++## Comparison with alternatives++| | LangGraph | CrewAI | PydanticAI | CubePi |+|---|---|---|---|---|+| Abstraction | State graph (nodes + edges) | Role-based crews and tasks | Typed agents with dependency injection | Plain async while-loop |+| Streaming | Callback-based, multiple modes | Limited | `async for` | `async for event in stream` |+| Checkpointing | Full snapshot per step | None built-in | None built-in | Append-only, O(1) per turn |+| Core deps | langchain-core + transitive | crewai + many | pydantic-ai | anthropic + openai + pydantic |+| Observability | LangSmith/Langfuse | None built-in | Logfire (optional) | Native OpenTelemetry |++## Links++- Homepage: https://cubepi.ai+- Documentation: https://cubepi.ai/docs+- GitHub: https://github.com/cubeplexai/cubepi+- PyPI: https://pypi.org/project/cubepi/+- Changelog: https://cubepi.ai/changelog+- vs LangGraph: https://cubepi.ai/compare/langgraph+- vs pi-agent-core: https://cubepi.ai/compare/pi-agent-core+- Twitter/X: https://x.com/cubeplexai++## License++MITdiff --git a/website/static/robots.txt b/website/static/robots.txtindex ba3369d..547384e 100644--- a/website/static/robots.txt+++ b/website/static/robots.txt@@ -3,3 +3,19 @@ Allow: /Sitemap: https://cubepi.ai/sitemap.xmlSitemap: https://cubepi.ai/zh-Hans/sitemap.xml++# AI/LLM crawlers — explicitly allowed+User-agent: GPTBot+Allow: /++User-agent: ClaudeBot+Allow: /++User-agent: PerplexityBot+Allow: /++User-agent: anthropic-ai+Allow: /++# LLM context file (https://llmstxt.org)+LLMs: https://cubepi.ai/llms.txtdiff --git a/website/versioned_docs/version-0.9/guides/agents/prompt-caching.md b/website/versioned_docs/version-0.9/guides/agents/prompt-caching.mdnew file mode 100644index 0000000..61518de--- /dev/null+++ b/website/versioned_docs/version-0.9/guides/agents/prompt-caching.md@@ -0,0 +1,237 @@+---+title: Prompt Caching+description: "How CubePi maximises prompt cache hit rates — append-only message storage, automatic cache breakpoints, and how to avoid breaking the cache."+---++# Prompt Caching++Prompt caching lets LLM providers reuse the KV computation for the+stable prefix of a request instead of reprocessing it on every turn.+The savings are significant: Anthropic charges cached tokens at+**10% of the normal input price**, and cache hits also reduce+time-to-first-token.++CubePi is designed from the ground up to maximise cache hit rates.+This guide explains how caching works, why CubePi's architecture+keeps the cache warm, and what you can do (or avoid doing) to+preserve those hits.++---++## How prompt caching works++Every LLM API request is a sequence of content blocks: system prompt,+tool definitions, then the conversation history. The provider hashes+the byte content of each block. If an incoming request shares a+prefix with a recently-seen request up to the TTL, the cached KV+state for that prefix is reused — the provider only processes the+new tokens beyond the cache boundary.++```+Request N: [system] [tools] [msg 1] [msg 2] [msg 3]+ ↑ ↑ ↑+ cached cached cached ← all hits on turn N+1+ [msg 4] ← new tokens only+```++Two things are required for a cache hit:++1. **The prefix is byte-identical** to the previous request. Any+ change — reordering, reformatting, adding a character — is a miss.+2. **The TTL hasn't expired.** Anthropic offers 5-minute (`"short"`)+ and 1-hour (`"long"`) retention; OpenAI caches automatically for+ prompts over 1 024 tokens.++---++## Why append-only storage matters++Many agent frameworks rebuild the full message list from a checkpoint+snapshot on every turn. If serialisation details change — dict key+ordering, whitespace, a timestamp field — the resulting byte sequence+differs from the previous request and **every cache breakpoint from+that point on misses**.++CubePi's checkpointer is append-only: it only ever adds new messages+to the end of the thread. The in-memory `agent.state.messages` list+grows by appending; it is never rebuilt or reshuffled. This means the+prefix of every request is guaranteed to be byte-identical to the+previous turn, which is the most fundamental requirement for cache+hits.++---++## Anthropic: automatic cache breakpoints++`AnthropicProvider` inserts `cache_control` markers automatically+via `DefaultCacheMarkerPolicy`. By default, three breakpoints are+placed on each request:++| Breakpoint | What gets cached | Why here |+|---|---|---|+| System prompt | The full system prompt block | Most stable content — rarely changes across turns |+| Last tool definition | All tool schemas up to and including the last one | Tool lists change infrequently |+| Last message in history | All prior conversation history | Moves forward each turn; prior turns stay warm |++On turn N+1, the first two breakpoints are identical to turn N (same+system prompt, same tools), so they get cache hits. The+last-message breakpoint has moved one message forward, so it writes+a new cache entry covering the slightly-longer history — and that+entry will be a hit on turn N+2.++### Configuration++```python+from cubepi.providers.anthropic import AnthropicProvider++# Default: short TTL (5 min), automatic breakpoints+provider = AnthropicProvider(api_key="…")++# Long TTL (1 h) — use when turns are slow or infrequent+provider = AnthropicProvider(api_key="…", cache_retention="long")++# Disable caching entirely+provider = AnthropicProvider(api_key="…", cache_retention="none")+```++### Reading cache metrics++Each `AssistantMessage` carries a `Usage` object. The cache fields:++```python+agent.subscribe(lambda event, signal=None: None)+await agent.prompt("Summarise the document")++last_msg = agent.state.messages[-1] # AssistantMessage+usage = last_msg.usage+print(usage.input_tokens) # total prompt tokens (inclusive of cache_read)+print(usage.cache_read_tokens) # tokens served from cache ← savings here+print(usage.cache_write_tokens) # tokens written to cache this turn+```++Cache hit rate for a turn: `cache_read_tokens / input_tokens`.++:::tip+`input_tokens` in CubePi's `Usage` is the **inclusive** total (prompt+= input + cache_read + cache_creation). Do **not** add `cache_read_tokens`+to the denominator — you would be double-counting.+:::++You can also see these fields in the `cubepi trace` CLI output and in+the OTel spans emitted by `Tracer`:++```+gen_ai.usage.input_tokens = 8 420 (inclusive)+gen_ai.usage.cache_read.input_tokens = 7 980 (subset)+```++---++## OpenAI: automatic caching++OpenAI caches automatically for prompts longer than 1 024 tokens —+no explicit `cache_control` markers are needed. CubePi surfaces the+hit data through the same `Usage` interface:++```python+usage.cache_read_tokens # maps to prompt_tokens_details.cached_tokens+```++There is nothing to configure on the CubePi side. Keep the system+prompt and tool definitions stable across turns and OpenAI's cache+will warm up naturally.++---++## How to avoid breaking the cache++### ✅ Do++- **Keep the system prompt stable across turns.** The system prompt+ is the outermost cache breakpoint. Changing it invalidates+ everything.+- **Keep the tool list stable.** Add or remove tools between+ *conversations*, not between *turns*. The tool-definition+ breakpoint covers the entire tool list; any change invalidates+ from there.+- **Use `cache_retention="long"`** if your agent turns take more than+ 5 minutes (long thinking runs, slow tools, infrequent users).+- **Use `agent.steer()`** to inject mid-turn guidance instead of+ prepending a new message to history — steer appends, not inserts.++### ❌ Avoid++- **Injecting messages into the middle of history.** Inserting a+ message before the last position shifts all subsequent messages,+ making the sequence differ from what the provider cached.+- **Changing the system prompt to include per-request data** (e.g.+ current timestamp, request ID). Put volatile data in the user+ message instead.+- **Reordering tool definitions.** The tool list is serialised in+ order; changing the order is a cache miss even if the tools+ themselves are identical.+- **Modifying a tool's description between turns** for the same+ thread. Description changes are serialised into the schema and+ will break the tool-definition breakpoint.++---++## Custom cache policy (Anthropic)++If the default three-breakpoint strategy does not fit your use case,+implement `CacheMarkerPolicy` and pass it to the provider:++```python+from cubepi.providers.anthropic import CacheMarkerPolicy, AnthropicProvider+from cubepi.providers.base import Message++class SystemOnlyPolicy:+ """Cache only the system prompt — useful when tool lists change often."""++ def mark_system(self) -> bool:+ return True++ def mark_last_tool(self) -> bool:+ return False++ def message_breakpoint_indices(self, messages: list[Message]) -> list[int]:+ return [] # no message breakpoints++provider = AnthropicProvider(+ api_key="…",+ cache_policy=SystemOnlyPolicy(),+)+```++The three methods map directly onto the three default breakpoints.+Return `True` / a non-empty list to enable a breakpoint, `False` /+`[]` to skip it.++---++## Multi-tenant considerations++In a multi-tenant setup each `thread_id` is an independent+conversation. Cache hits are per-thread: user A's history warms a+cache entry that benefits only user A's subsequent turns.++For maximum cache efficiency across tenants:++- Use a **stable, shared system prompt** for all tenants rather than+ embedding per-tenant data in the system prompt. Per-tenant context+ belongs in the first user message or in tool results.+- Keep tool definitions identical across all tenant agents. If+ different tenants need different tool sets, consider separate+ `Agent` instances with separate `AnthropicProvider` configurations+ rather than dynamically mutating the tool list.++---++## See also++- [Anthropic Provider](../providers/anthropic) — `cache_retention`,+ `CacheMarkerPolicy`, and the `on_payload` hook for inspecting raw requests.+- [Multi-turn Conversations](./multi-turn) — how message history grows+ across turns and why append semantics matter.+- [Tracing](../tracing/overview) — reading `cache_read.input_tokens`+ from OTel spans.diff --git a/website/versioned_sidebars/version-0.9-sidebars.json b/website/versioned_sidebars/version-0.9-sidebars.jsonindex cd7421a..92ba992 100644--- a/website/versioned_sidebars/version-0.9-sidebars.json+++ b/website/versioned_sidebars/version-0.9-sidebars.json@@ -23,7 +23,8 @@"guides/agents/tool-use","guides/agents/multi-turn","guides/agents/streaming",- "guides/agents/forking"+ "guides/agents/forking",+ "guides/agents/prompt-caching"]},{