Domain fragments capture domain-specific knowledge that can be injected into AI prompts. They help the AI understand your business vocabulary, rules, constraints, and processes.
import { term } from '@deepagents/context';// Finance domainterm('NPL', 'non-performing loan - loan past due 90+ days');term('basis points', 'one hundredth of a percentage point (1% = 100 bps)');term('AUM', 'assets under management - total market value of client investments');// Logistics domainterm('deadhead miles', 'distance driven with empty truck between deliveries');term('dwell time', 'total time a truck spends at a loading dock or warehouse');term('LTL', 'less than truckload - shipment that doesn\'t fill entire truck');
Use term() for simple, direct mappings between business terms and their meanings. For more complex explanations, use explain().
import { hint } from '@deepagents/context';// Manufacturing domainhint('Always exclude work orders with status = "simulation" from production metrics');hint('When calculating OEE, only count scheduled production time');hint('Defect rates should be calculated per batch, not per individual unit');// Real Estate domainhint('Never include properties with listing_status = "draft" in market analysis');hint('Always filter out duplicate MLS listings');hint('Square footage comparisons must specify if including basement/garage');
Hints use imperative language (“Always exclude…”, “Never include…”) to make the rule clear and actionable.
import { guardrail } from '@deepagents/context';// Healthcareguardrail({ rule: 'Never return PHI like SSN, MRN, or full address', reason: 'HIPAA compliance', action: 'Offer de-identified aggregates instead',});// Financeguardrail({ rule: 'Block any query exposing employee-level compensation by name', reason: 'Confidential payroll data', action: 'Provide ranges grouped by department or level',});// Performanceguardrail({ rule: 'Warn when query would scan more than 10M rows', reason: 'Performance and cost control', action: 'Ask user to add filters before proceeding',});
Guardrails represent “never do” rules. They should be explicit and include an action field explaining what to do instead.
import { explain } from '@deepagents/context';// Gaming domainexplain({ concept: 'DAU to MAU ratio', explanation: 'like measuring how many club members visit daily vs just once a month - shows stickiness', therefore: 'Calculate as DAU / MAU, where higher ratio means more engaged user base',});// HR domainexplain({ concept: 'time to fill', explanation: 'like measuring how long a house sits on the market - from posting job to accepting offer', therefore: 'Calculate as days between job_posted_date and offer_accepted_date',});
Use explain() when a simple definition isn’t enough. The explanation field should use analogies or metaphors to convey deeper understanding.
import { example } from '@deepagents/context';// Energy domainexample({ question: 'show me peak demand hours for the last week', answer: 'SELECT DATE_TRUNC(\'hour\', timestamp) as hour, MAX(kwh) as peak FROM readings WHERE timestamp >= CURRENT_DATE - 7 GROUP BY hour ORDER BY peak DESC LIMIT 10',});// Agriculture domainexample({ question: 'what is the average yield per acre by crop type this season', answer: 'SELECT crop_type, AVG(harvest_quantity / field_acres) as yield_per_acre FROM harvests WHERE harvest_date >= \'2024-01-01\' GROUP BY crop_type',});// Travel domainexample({ question: 'show me hotel occupancy rate for this month', answer: 'SELECT hotel_name, (SUM(occupied_rooms) / SUM(total_rooms)) * 100 as occupancy_rate FROM daily_occupancy WHERE date >= DATE_TRUNC(\'month\', CURRENT_DATE) GROUP BY hotel_id, hotel_name', note: 'Occupancy rate is a percentage - multiply by 100',});
import { clarification } from '@deepagents/context';// Marketing domainclarification({ when: 'user asks for "conversion rate"', ask: 'Which conversion: click-to-lead, lead-to-opportunity, or opportunity-to-customer?', reason: 'Conversion rate means different things at each funnel stage',});// Food Deliveryclarification({ when: 'user asks about "delivery time"', ask: 'Do you mean estimated time at order, actual delivery time, or time from kitchen to door?', reason: 'Multiple time metrics exist with different business implications',});
import { workflow } from '@deepagents/context';// Insurance domainworkflow({ task: 'Claims Loss Ratio Analysis', triggers: ['loss ratio', 'claims ratio', 'underwriting performance'], steps: [ 'Calculate total claims paid for each policy period', 'Calculate total premiums earned for same period', 'Compute loss ratio as (claims_paid / premiums_earned) * 100', 'Segment by policy type, geography, and underwriter', 'Identify policies with loss ratio > 100% (losing money)', 'Calculate trend over time using rolling 12-month windows', ], notes: 'Use incurred date for claims, not paid date',});// Sports Analyticsworkflow({ task: 'Player Performance Rating', triggers: ['player rating', 'performance score'], steps: [ 'Aggregate per-game stats: points, assists, rebounds', 'Calculate efficiency metrics: shooting %, plus/minus', 'Normalize each metric using z-scores vs league average', 'Apply position-specific weights to each metric', 'Combine weighted scores into overall rating (0-100)', 'Rank players within position group', ], notes: 'Update weights each season based on game trends',});
import { quirk } from '@deepagents/context';// Government domainquirk({ issue: 'Citizen IDs contain leading zeros but stored as integers', workaround: 'Use LPAD(citizen_id::VARCHAR, 10, \'0\') to restore zeros',});// Aviation domainquirk({ issue: 'Flight times crossing midnight show as negative duration', workaround: 'Add 24 hours when duration < 0: CASE WHEN duration < 0 THEN duration + INTERVAL \'24 hours\' END',});// Automotive domainquirk({ issue: 'VIN numbers with letter O incorrectly entered as zero in legacy data', workaround: 'Use REPLACE(vin, \'0\', \'O\') or fuzzy matching for both cases',});
Choose the fragment type that best matches your intent:
term: Simple vocabulary
hint: Behavioral rules
guardrail: Safety boundaries
example: Concrete demonstrations
workflow: Multi-step processes
Be Specific and Actionable
Write clear, actionable content:
// Good: Specific and actionablehint('Always exclude orders with status = "test" from revenue calculations');// Avoid: Vaguehint('Be careful with test data');
Include Context in Guardrails
Always provide reason and action fields:
guardrail({ rule: 'Never expose PII', reason: 'GDPR compliance', action: 'Aggregate or anonymize data instead',});
Use Analogies for Complex Concepts
When explaining complex metrics, use real-world analogies:
explain({ concept: 'churn rate', explanation: 'like a leaky bucket - measures how fast you lose customers vs gain new ones', therefore: 'Calculate as (customers_lost / total_customers_start) * 100',});