@fastpaca/cria 0.0.1 → 1.1.3

package/README.md

@@ -1,15 +1,17 @@
 <h1 align="center">Cria</h1>
 
 <p align="center">
-  Cria is a tiny library for building LLM prompts as reusable components.
+  <i>Your prompts deserve the same structure as your code.</i>
 </p>
 
 <p align="center">
-  <i>Debug, view, and save your prompts easily. Swap out components without major rewrites and test your prompts.</i>
+  <b><i>Cria turns prompts into composable components with explicit roles and strategies, and works with your existing environment & frameworks.</i></b>
 </p>
 
 <p align="center">
+  <a href="https://github.com/fastpaca/cria/actions/workflows/ci.yml"><img src="https://github.com/fastpaca/cria/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/@fastpaca/cria"><img src="https://img.shields.io/npm/v/@fastpaca/cria?logo=npm&logoColor=white" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/@fastpaca/cria"><img src="https://img.shields.io/npm/dm/@fastpaca/cria" alt="Downloads"></a>
   <a href="https://opensource.org/license/mit"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
 </p>
 
@@ -19,147 +21,142 @@
   </a>
 </p>
 
-Most prompt construction is string concatenation. Append everything to some buffer, hope the important parts survive when you hit limits or want to save cost.
-
-Cria lets you declare what's expendable and what is not, and makes your prompts failure mode explicit.
-
-Cria treats memory layout as a first-class concern. You declare priorities upfront, and the library handles eviction when needed. Components let you test retrieval logic separately from system prompts, swap implementations without rewrites, and debug exactly which content got cut when quality degrades.
-
-```tsx
-const prompt = (
-  <Region priority={0}>
-    You are a helpful assistant.
-
-    {/* Only preserve 80k tokens of history */}
-    <Truncate budget={80000} priority={2}>
-      {conversationHistory}
-    </Truncate>
-
-    {/* Only preserve 20k tokens of tool calls. It gets dropped
-        first in case we need to. */}
-    <Truncate budget={20000} priority={3}>
-      {toolCalls}
-    </Truncate>
-
-    {/* Skip examples in case we are bad on budget */}
-    <Omit priority={3}>{examples}</Omit>
-
-    {userMessage}
-  </Region>
-);
-
-render(prompt, { tokenizer, budget: 128000 });
+Cria is a lightweight prompt composition library for structured prompt engineering. Build prompts as components, keep behavior predictable, and reuse the same structure across providers. Runs on Node, Deno, Bun, and Edge; adapters require their SDKs.
+
+```ts
+const messages = await cria
+  .prompt()
+  .system("You are a research assistant.")
+  .vectorSearch({ store, query: question, limit: 10 })
+  .provider(openai("gpt-5-nano"), p => p
+    .summary(conversation, { store: memory })
+    .last(conversation, { N: 20 })
+  )
+  .user(question)
+  .render({ budget: 200_000, renderer });
 ```
 
-Cria will drop lower priority sections or truncate them in case it hits your prompt limits.
-## Features
+See all **[-> Documentation](docs/README.md)** for more comprehensive overviews.
 
-- **Composable** — Build prompts from reusable components. Test and optimize each part independently.
-- **Priority-based** — Declare what's sacred (priority 0) and what's expendable (priority 3). No more guessing what gets cut.
-- **Flexible strategies** — Truncate content progressively, omit entire sections, or write custom eviction logic.
-- **Tiny** — Zero dependencies.
+## Use Cria when you need...
 
-## Getting Started
+- **Need RAG?** Call `.vectorSearch({ store, query })`.
+- **Need a summary for long conversations?** Use `.summary(...)`.
+- **Need to cap history but keep structure?** Use `.last(...)`.
+- **Need to drop optional context when the context window is full?** Use `.omit(...)`.
+- **Using AI SDK?** Plug and play with `@fastpaca/cria/ai-sdk`!
+- **Prefer TSX?** Import the optional JSX surface from `@fastpaca/cria/jsx`.
 
-```bash
-npm install @fastpaca/cria
-```
-
-Add to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "@fastpaca/cria"
-  }
-}
-```
+## Integrations
 
-## Documentation
+<details>
+<summary><strong>OpenAI Chat Completions</strong></summary>
 
-### Components
+```ts
+import OpenAI from "openai";
+import { chatCompletions } from "@fastpaca/cria/openai";
+import { cria } from "@fastpaca/cria";
 
-**`<Region>`** — The basic building block. Groups content with a priority level.
-
-```jsx
-<Region>
-  <Region priority={0}>System instructions</Region>
-  <Region priority={2}>Retrieved context</Region>
-</Region>
+const client = new OpenAI();
+const messages = await cria
+  .prompt()
+  .system("You are helpful.")
+  .user(userQuestion)
+  .render({ budget, tokenizer, renderer: chatCompletions });
+const response = await client.chat.completions.create({ model: "gpt-4o-mini", messages });
 ```
-
-**`<Truncate>`** — Progressively shortens content when over budget.
-
-```jsx
-<Truncate budget={10000} from="start" priority={2}>
-  {longConversation}
-</Truncate>
+</details>
+
+<details>
+<summary><strong>OpenAI Responses</strong></summary>
+
+```ts
+import OpenAI from "openai";
+import { responses } from "@fastpaca/cria/openai";
+import { cria } from "@fastpaca/cria";
+
+const client = new OpenAI();
+const input = await cria
+  .prompt()
+  .system("You are helpful.")
+  .user(userQuestion)
+  .render({ budget, tokenizer, renderer: responses });
+const response = await client.responses.create({ model: "gpt-5-nano", input });
 ```
-
-**`<Omit>`** — Drops entirely when space is needed.
-
-```jsx
-<Omit priority={3}>{optionalExamples}</Omit>
+</details>
+
+<details>
+<summary><strong>Anthropic</strong></summary>
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { anthropic } from "@fastpaca/cria/anthropic";
+import { cria } from "@fastpaca/cria";
+
+const client = new Anthropic();
+const { system, messages } = await cria
+  .prompt()
+  .system("You are helpful.")
+  .user(userQuestion)
+  .render({ budget, tokenizer, renderer: anthropic });
+const response = await client.messages.create({ model: "claude-haiku-4-5", system, messages });
 ```
-
-### Priority Levels
-
-Lower number = higher importance.
-
-| Priority | Use for |
-|----------|---------|
-| 0 | System prompt, safety rules |
-| 1 | Current user message, tool outputs |
-| 2 | Conversation history, retrieved docs |
-| 3 | Examples, optional context |
-
-### Tokenizer
-
-Pass any function that counts tokens:
-
-```tsx
-import { encoding_for_model } from "tiktoken";
-
-const enc = encoding_for_model("gpt-4");
-const tokenizer = (text: string) => enc.encode(text).length;
-
-render(prompt, { tokenizer, budget: 128000 });
+</details>
+
+<details>
+<summary><strong>Vercel AI SDK</strong></summary>
+
+```ts
+import { renderer } from "@fastpaca/cria/ai-sdk";
+import { cria } from "@fastpaca/cria";
+import { generateText } from "ai";
+
+const messages = await cria
+  .prompt()
+  .system("You are helpful.")
+  .user(userQuestion)
+  .render({ budget, tokenizer, renderer });
+const { text } = await generateText({ model, messages });
 ```
+</details>
 
-### Custom Strategies
+## Roadmap
 
-Write your own eviction logic:
+**Done**
 
-```tsx
-import type { Strategy } from "@fastpaca/cria";
+- [x] Fluent DSL and priority-based eviction
+- [x] Components: Region, Message, Truncate, Omit, Last, Summary, VectorSearch, ToolCall, ToolResult, Reasoning, Examples, CodeBlock, Separator
+- [x] Renderers: OpenAI (Chat Completions + Responses), Anthropic, AI SDK
+- [x] AI SDK helpers: Messages component, DEFAULT_PRIORITIES
+- [x] Memory: InMemoryStore, Redis, Postgres, Chroma, Qdrant
+- [x] Observability: render hooks, validation schemas, snapshots, OpenTelemetry
+- [x] Tokenizer helpers
 
-const summarize: Strategy = ({ target, tokenizer }) => {
-  const summary = createSummary(target.content);
-  return [{ ...target, content: summary, tokens: tokenizer(summary) }];
-};
+**Planned**
 
-<Region priority={2} strategy={summarize}>{document}</Region>
-```
+- [ ] Next.js adapter
+- [ ] GenAI semantic conventions for OpenTelemetry
+- [ ] Visualization tool
+- [ ] Prompt eval / testing functionality
 
-### Error Handling
+## Contributing
 
-```tsx
-import { FitError } from "@fastpaca/cria";
+- Issues and PRs are welcome.
+- Keep changes small and focused.
+- If you add a feature, include a short example or doc note.
+- Prefer DSL-based examples in contributions; JSX lives under `@fastpaca/cria/jsx` as optional sugar.
 
-try {
-  render(prompt, { tokenizer, budget: 1000 });
-} catch (e) {
-  if (e instanceof FitError) {
-    console.log(`Over budget by ${e.overBudgetBy} tokens`);
-  }
-}
-```
+## Support
 
-## Contributing
+- Open a GitHub issue for bugs or feature requests.
+- For quick questions, include a minimal repro or snippet.
+
+## FAQ
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+- **Does this replace my LLM SDK?** No - Cria builds prompt structures. You still use your SDK to call the model.
+- **How do I tune token budgets?** Pass `budget` to `render()` and set priorities on regions. Providers include tiktoken defaults; see [docs/tokenization.md](docs/tokenization.md) to bring your own.
+- **Is this production-ready?** Not yet! It is a work in progress and you should test it out before you run this in production.
 
 ## License
 
-MIT © [Fastpaca](https://fastpaca.com)
+MIT

package/dist/ai-sdk/index.d.ts

@@ -0,0 +1,68 @@
+import type { LanguageModel, ModelMessage, UIMessage } from "ai";
+import type { CompletionRequest, CompletionResult, MaybePromise, ModelProvider, PromptChildren, PromptElement, PromptRenderer, Tokenizer } from "../types";
+/**
+ * Priority configuration for message types when rendering prompts.
+ * Lower numbers = higher priority (less likely to be dropped).
+ */
+export interface Priorities {
+    system: number;
+    user: number;
+    assistant: number;
+    toolCall: number;
+    toolResult: number;
+    reasoning: number;
+}
+export declare const DEFAULT_PRIORITIES: Priorities;
+export interface MessagesProps {
+    messages: readonly UIMessage[];
+    includeReasoning?: boolean;
+    priorities?: Partial<Priorities>;
+    id?: string;
+}
+/**
+ * Converts AI SDK UIMessages into Cria prompt elements.
+ * Use this to include conversation history in your prompts.
+ */
+export declare function Messages({ messages, includeReasoning, priorities, id, }: MessagesProps): PromptElement;
+/**
+ * Renderer that outputs ModelMessage[] for use with the Vercel AI SDK.
+ * Pass this to render() to get messages compatible with generateText/streamText.
+ */
+export declare const renderer: PromptRenderer<ModelMessage[]>;
+interface AISDKProviderProps {
+    /** The language model to use (e.g. openai("gpt-4o"), anthropic("claude-sonnet-4-20250514")) */
+    model: LanguageModel;
+    /** Optional tokenizer to use for budgeting; defaults to an approximate counter */
+    tokenizer?: Tokenizer;
+    /** Child components that will have access to this provider */
+    children?: PromptChildren;
+}
+/**
+ * ModelProvider implementation that wraps an AI SDK LanguageModel.
+ * Use this with the DSL's `.provider()` method.
+ *
+ * @example
+ * ```typescript
+ * import { cria } from "@fastpaca/cria";
+ * import { Provider } from "@fastpaca/cria/ai-sdk";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const provider = new Provider(openai("gpt-4o"));
+ *
+ * const prompt = cria
+ *   .prompt()
+ *   .provider(provider, (p) =>
+ *     p.summary(content, { id: "summary", store })
+ *   )
+ *   .build();
+ * ```
+ */
+export declare class Provider implements ModelProvider {
+    readonly name = "ai-sdk";
+    private readonly model;
+    constructor(model: LanguageModel);
+    completion(request: CompletionRequest): Promise<CompletionResult>;
+}
+export declare function AISDKProvider({ model, tokenizer, children, }: AISDKProviderProps): MaybePromise<PromptElement>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EAEZ,SAAS,EACV,MAAM,IAAI,CAAC;AAmBZ,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EAEb,cAAc,EACd,aAAa,EACb,cAAc,EAEd,SAAS,EACV,MAAM,UAAU,CAAC;AAElB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,kBAAkB,EAAE,UAOhC,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,gBAAwB,EACxB,UAAU,EACV,EAAE,GACH,EAAE,aAAa,GAAG,aAAa,CAgB/B;AA0LD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,cAAc,CAAC,YAAY,EAAE,CAKnD,CAAC;AAoMF,UAAU,kBAAkB;IAC1B,+FAA+F;IAC/F,KAAK,EAAE,aAAa,CAAC;IACrB,kFAAkF;IAClF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AA4BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAS,YAAW,aAAa;IAC5C,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;gBAE1B,KAAK,EAAE,aAAa;IAI1B,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAkBxE;AAED,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,SAAS,EACT,QAAa,GACd,EAAE,kBAAkB,GAAG,YAAY,CAAC,aAAa,CAAC,CA+BlD"}