@deepagents/context 0.10.2 → 0.12.0

package/README.md

@@ -4,7 +4,7 @@ A domain-agnostic context management system for formatting context fragments int
 
 ## Overview
 
-This package provides a simple and flexible way to render context data in multiple formats (XML, Markdown, TOML). Context fragments are simple data structures that can be transformed into different representations suitable for various LLM prompt styles.
+This package provides a flexible way to compose and render context data in multiple formats (XML, Markdown, TOML, TOON). Context fragments are simple data structures that can be transformed into different representations suitable for various LLM prompt styles.
 
 ## Installation
 
@@ -15,106 +15,156 @@ npm install @deepagents/context
 ## Basic Usage
 
 ```typescript
-import {
-  MarkdownRenderer,
-  TomlRenderer,
-  XmlRenderer,
-} from '@deepagents/context';
-import type { ContextFragment } from '@deepagents/context';
-
-// Define your context fragments
-const fragments: ContextFragment[] = [
-  {
-    name: 'styleGuide',
-    data: {
-      prefer: 'CTEs',
-      never: 'subqueries',
-      indentation: 2,
-    },
-  },
+import { XmlRenderer, guardrail, hint, term } from '@deepagents/context';
+
+// Create fragments using builder functions
+const fragments = [
+  term('MRR', 'monthly recurring revenue'),
+  hint('Always exclude test accounts'),
+  guardrail({
+    rule: 'Never expose PII',
+    reason: 'Privacy compliance',
+    action: 'Aggregate data instead',
+  }),
 ];
 
-// Render in different formats
-const xmlRenderer = new XmlRenderer();
-console.log(xmlRenderer.render(fragments));
+// Render to XML
+const renderer = new XmlRenderer({ groupFragments: true });
+console.log(renderer.render(fragments));
+```
 
-const mdRenderer = new MarkdownRenderer();
-console.log(mdRenderer.render(fragments));
+**Output:**
 
-const tomlRenderer = new TomlRenderer();
-console.log(tomlRenderer.render(fragments));
-```
+```xml
+<terms>
+  <term>
+    <name>MRR</name>
+    <definition>monthly recurring revenue</definition>
+  </term>
+</terms>
+<hints>
+  <hint>Always exclude test accounts</hint>
+</hints>
+<guardrails>
+  <guardrail>
+    <rule>Never expose PII</rule>
+    <reason>Privacy compliance</reason>
+    <action>Aggregate data instead</action>
+  </guardrail>
+</guardrails>
+```
+
+## Fragment Builders
+
+### Domain Fragments
+
+Builder functions for injecting domain knowledge into prompts:
+
+| Function                                      | Description                      | Example                                             |
+| --------------------------------------------- | -------------------------------- | --------------------------------------------------- |
+| `term(name, definition)`                      | Define business vocabulary       | `term('NPL', 'non-performing loan')`                |
+| `hint(text)`                                  | Behavioral rules and constraints | `hint('Always filter by status')`                   |
+| `guardrail({rule, reason?, action?})`         | Safety rules and boundaries      | `guardrail({ rule: 'No PII' })`                     |
+| `explain({concept, explanation, therefore?})` | Rich concept explanations        | `explain({ concept: 'churn', explanation: '...' })` |
+| `example({question, answer, note?})`          | Question-answer pairs            | `example({ question: '...', answer: '...' })`       |
+| `clarification({when, ask, reason})`          | When to ask for more info        | `clarification({ when: '...', ask: '...' })`        |
+| `workflow({task, steps, triggers?, notes?})`  | Multi-step processes             | `workflow({ task: '...', steps: [...] })`           |
+| `quirk({issue, workaround})`                  | Data edge cases                  | `quirk({ issue: '...', workaround: '...' })`        |
+| `styleGuide({prefer, never?, always?})`       | Style preferences                | `styleGuide({ prefer: 'CTEs' })`                    |
+| `analogy({concepts, relationship, ...})`      | Concept comparisons              | `analogy({ concepts: [...], relationship: '...' })` |
+| `glossary(entries)`                           | Term-to-expression mapping       | `glossary({ revenue: 'SUM(amount)' })`              |
+
+### User Fragments
+
+Builder functions for user-specific context:
+
+| Function                             | Description                  | Example                                        |
+| ------------------------------------ | ---------------------------- | ---------------------------------------------- |
+| `identity({name?, role?})`           | User identity                | `identity({ role: 'VP Sales' })`               |
+| `persona({name, role, tone?})`       | AI persona definition        | `persona({ name: 'Freya', role: '...' })`      |
+| `alias(term, meaning)`               | User-specific vocabulary     | `alias('revenue', 'gross revenue')`            |
+| `preference(aspect, value)`          | Output preferences           | `preference('date format', 'YYYY-MM-DD')`      |
+| `userContext(description)`           | Current working focus        | `userContext('Q4 analysis')`                   |
+| `correction(subject, clarification)` | Corrections to understanding | `correction('status', '1=active, 0=inactive')` |
+
+### Core Utilities
+
+| Function                      | Description                                    |
+| ----------------------------- | ---------------------------------------------- |
+| `fragment(name, ...children)` | Create a wrapper fragment with nested children |
+| `role(content)`               | System role/instructions fragment              |
 
 ## Renderers
 
+All renderers support the `groupFragments` option which groups same-named fragments under a pluralized parent tag.
+
 ### XmlRenderer
 
 Renders fragments as XML with proper nesting and escaping:
 
+```typescript
+const renderer = new XmlRenderer({ groupFragments: true });
+```
+
 ```xml
 <styleGuide>
   <prefer>CTEs</prefer>
   <never>subqueries</never>
-  <indentation>2</indentation>
 </styleGuide>
 ```
 
-**Features:**
-
-- Automatic XML escaping for special characters
-- Nested object support
-- Array handling with singular form tags
-- Proper indentation
-
 ### MarkdownRenderer
 
 Renders fragments as Markdown with bullet points:
 
+```typescript
+const renderer = new MarkdownRenderer();
+```
+
 ```markdown
 ## Style Guide
 
 - **prefer**: CTEs
 - **never**: subqueries
-- **indentation**: 2
 ```
 
-**Features:**
-
-- Automatic title case conversion for fragment names
-- Nested structures with proper indentation
-- Array items as bullet points
-- Bold keys for readability
-
 ### TomlRenderer
 
 Renders fragments as TOML-like format:
 
+```typescript
+const renderer = new TomlRenderer();
+```
+
 ```toml
 [styleGuide]
 prefer = "CTEs"
 never = "subqueries"
-indentation = 2
 ```
 
-**Features:**
+### ToonRenderer
+
+Token-efficient format with CSV-style tables for uniform arrays:
+
+```typescript
+const renderer = new ToonRenderer();
+```
 
-- TOML section headers
-- Nested objects as subsections
-- Array support with proper formatting
-- String escaping for quotes and backslashes
+```yaml
+styleGuide:
+  prefer: CTEs
+  never: subqueries
+```
 
 ## Handling Complex Data
 
 ### Arrays
 
 ```typescript
-const fragment = {
-  name: 'workflow',
-  data: {
-    task: 'Analysis',
-    steps: ['step1', 'step2', 'step3'],
-  },
-};
+const fragment = workflow({
+  task: 'Analysis',
+  steps: ['step1', 'step2', 'step3'],
+});
 ```
 
 **XML Output:**
@@ -130,26 +180,6 @@ const fragment = {
 </workflow>
 ```
 
-**Markdown Output:**
-
-```markdown
-## Workflow
-
-- **task**: Analysis
-- **steps**:
-  - step1
-  - step2
-  - step3
-```
-
-**TOML Output:**
-
-```toml
-[workflow]
-task = "Analysis"
-steps = ["step1", "step2", "step3"]
-```
-
 ### Nested Objects
 
 ```typescript
@@ -177,42 +207,9 @@ const fragment = {
 </database>
 ```
 
-**Markdown Output:**
-
-```markdown
-## Database
-
-- **host**: localhost
-- **settings**:
-  - **timeout**: 30
-  - **retry**: true
-```
-
-**TOML Output:**
-
-```toml
-[database]
-host = "localhost"
-
-[settings]
-timeout = 30
-retry = true
-```
-
 ### Null and Undefined Values
 
-All renderers automatically skip `null` and `undefined` values:
-
-```typescript
-const fragment = {
-  name: 'config',
-  data: {
-    enabled: true,
-    disabled: null, // Will be skipped
-    missing: undefined, // Will be skipped
-  },
-};
-```
+All renderers automatically skip `null` and `undefined` values.
 
 ## API Reference
 
@@ -223,31 +220,29 @@ const fragment = {
 ```typescript
 interface ContextFragment {
   name: string;
-  data: Record<string, unknown>;
+  data: FragmentData;
+  type?: 'fragment' | 'message';
+  persist?: boolean;
+  codec?: FragmentCodec;
 }
 ```
 
 #### ContextRenderer
 
 ```typescript
-interface ContextRenderer {
-  render(fragments: ContextFragment[]): string;
+abstract class ContextRenderer {
+  abstract render(fragments: ContextFragment[]): string;
 }
 ```
 
 ### Classes
 
-All renderer classes implement the `ContextRenderer` interface:
+All renderer classes extend `ContextRenderer`:
 
 - `XmlRenderer` - Renders as XML
 - `MarkdownRenderer` - Renders as Markdown
 - `TomlRenderer` - Renders as TOML
-
-Each class has a single public method:
-
-```typescript
-render(fragments: ContextFragment[]): string
-```
+- `ToonRenderer` - Token-efficient format
 
 ## License
 

package/dist/example-error-recovery.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=example-error-recovery.d.ts.map

package/dist/example-error-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-error-recovery.d.ts","sourceRoot":"","sources":["../src/example-error-recovery.ts"],"names":[],"mappings":""}