Text2SQL - Natural Language to SQL

Domain-agnostic context management for LLM applications with rendering, persistence, chat orchestration, and sandbox tooling

The @deepagents/context package provides primitives for composing LLM context: organizing fragments, rendering them to multiple prompt formats, persisting conversations, orchestrating chat flows, and estimating usage costs. It is the foundation layer that other DeepAgents packages build upon.

It also ships the sandbox layer used by the rest of the repo: direct virtual execution, Docker containers, Agent OS backends, and the shared bash tool wrapper for agents.

The Problem with Ad-Hoc Context

When building LLM applications, context management often becomes messy:

String concatenation: System prompts grow through manual string assembly
No structure: Hard to organize different types of context (instructions, hints, conversation)
Format lock-in: Can't easily switch between XML, Markdown, or other formats
No persistence: Conversation history requires custom storage logic
Cost blindness: No way to predict API costs before making calls

Context Fragments

DeepAgents Context solves this through structured fragments. Instead of raw strings, you compose context from typed pieces:

import {
  ContextEngine,
  InMemoryContextStore,
  hint,
  role,
  user,
} from '@deepagents/context';

// Create a context engine with storage
const store = new InMemoryContextStore();
const context = new ContextEngine({ store }).set(
  role('You are a helpful assistant.'),
  hint('Be concise and friendly.'),
  hint('Use examples when explaining concepts.'),
);

// Add a user message
context.set(user('What is TypeScript?'));

// Resolve for AI SDK consumption
const { systemPrompt, messages } = await context.resolve();
// systemPrompt: XML-rendered role + hints
// messages: [{ id: '...', role: 'user', parts: [{ type: 'text', text: 'What is TypeScript?' }] }]

The resolve() method automatically:

Separates message fragments from system context
Renders system context using your chosen format (XML by default)
Returns AI SDK-compatible output

Key Features

Feature	Description
Fragment Helpers	`role()`, `user()`, `assistant()`, `hint()`, `fragment()` for composing context
Fragment Serialization	`fromFragment()`, `toFragment()`, `encodeSerializedValue()` for storing non-message fragments as JSON
Multiple Renderers	XML, Markdown, TOML, TOON formats for different models and use cases
Persistence	SQLite and in-memory stores for conversation history
Sandbox Tooling	`createBashTool()`, `createVirtualSandbox()`, `createDockerSandbox()`, and real command execution backends
Cost Estimation	Token counting and pricing via models.dev for 1000+ models
AI SDK Integration	`resolve()` returns `systemPrompt` + `messages` ready for `generateText()`

Renderers at a Glance

Same context, four output formats:

const fragments = [
  role('You are a SQL expert.'),
  hint('Use CTEs for complex queries.'),
];

Renderer	Output
XML (default)	`<role>You are a SQL expert.</role>` `<hint>Use CTEs for complex queries.</hint>`
Markdown	`## Role` `You are a SQL expert.` `## Hint` `Use CTEs for complex queries.`
TOML	`role = "You are a SQL expert."` `hint = "Use CTEs for complex queries."`
TOON	`role: You are a SQL expert.` `hint: Use CTEs for complex queries.`

When to Use This Package

Ideal for:

Multi-turn conversations requiring persistence
Applications that need different prompt formats for different models
Cost-conscious systems that need to estimate before calling APIs
Projects using @deepagents/agent or @deepagents/text2sql

Consider alternatives when:

Simple one-shot prompts suffice
You don't need conversation history
Token counting isn't important

Integration with DeepAgents

The context package is designed to work seamlessly with other DeepAgents packages:

// With @deepagents/agent
const myAgent = agent({
  name: 'Assistant',
  model: groq('gpt-oss-20b'),
  prompt: async (ctx) => {
    const context = new ContextEngine({ store }).set(
      role('You are helpful.'),
      hint(ctx.preference),
    );
    return (await context.resolve()).systemPrompt;
  },
});

// With @deepagents/text2sql
const domainContext = new ContextEngine({ store }).set(
  fragment(
    'domain',
    hint('LTV means Lifetime Value'),
    hint('MRR means Monthly Recurring Revenue'),
  ),
);

Next Steps

Getting Started - Installation and first example
Architecture - Deep-dive into package design
Fragments - Fragment types and composition
Fragment Serialization - Store non-message fragments in your own database
Sandbox - Execute commands through virtual, Docker, or Agent OS backends
Renderers Overview - Choosing the right output format
Recipes - Real-world integration patterns

Overview