# Agent Notation — Complete Reference

## Overview

Agent Notation is a structured notation language that compresses natural language LLM prompts into a human-readable shorthand. It achieves up to 63% token reduction with zero processing overhead — no GPU, no fine-tuning, no model changes. It works with every LLM.

## Core Operators

| Operator | Name | Purpose | Example |
|----------|------|---------|---------|
| → | Flow | Data flow, transformation, return | input→output |
| \| | Conditional | Branches, alternatives | ok→save \| err→log |
| × | Group-By | Aggregation, dimensional breakdown | top5×revenue |
| + | Combine | Join related items | log+retry |
| ! | Negation | Prefix negation | !hallucinate |
| : | Type | Type declaration, role assignment | role:agent |
| [] | List | Collections, arrays | int[] |
| () | Scope | Parameters, grouping | fn(x,y) |
| % | Percentage | Ratios, proportional metrics | yoy% |
| @ | Targeting | Target entity or destination | deploy@prod |

## Standard Abbreviations

| Abbrev | Expansion | Category |
|--------|-----------|----------|
| fn | function | Code |
| ret | return | Code |
| val | validate | Code |
| iter | iterate | Code |
| cfg | configuration | Code |
| fmt | format | Code |
| req | request | Networking |
| res | response | Networking |
| ctx | context | LLM |
| rpt | report | Output |
| msg | message | Communication |
| err | error | Error handling |
| auth | authentication | Security |
| db | database | Storage |
| usr | user | Entity |
| doc | document | Content |
| tpl | template | Content |
| src | source | I/O |
| tgt | target | I/O |
| env | environment | Infrastructure |
| deps | dependencies | Infrastructure |
| params | parameters | Code |
| args | arguments | Code |
| opts | options | Code |
| impl | implementation | Code |
| init | initialize | Code |
| del | delete | CRUD |
| upd | update | CRUD |
| cust | customer | Business |
| prod | product | Business |
| rev | revenue | Business |
| txn | transaction | Business |
| inv | inventory | Business |

### Language Prefixes

py (Python), js (JavaScript), ts (TypeScript), rb (Ruby), go (Go), rs (Rust), java (Java), cs (C#), cpp (C++), sql (SQL), sh (Shell/Bash)

## Worked Examples

### 1. Code Generation (60% savings)

English (35 tokens):
"Write a Python function that takes a list of integers, filters even numbers, sorts them in descending order, and returns the result"

Agent Notation (14 tokens):
py fn(lst:int[])→int[]: filter even, sort desc

### 2. RAG / Contextual Q&A (71% savings)

English (35 tokens):
"Based on the context provided, answer the following question. If the answer is not found in the context, say 'answer not found'. Do not hallucinate or make up information."

Agent Notation (10 tokens):
ctx→answer | !found→'not in ctx' | !hallucinate

### 3. System Prompt (62% savings)

English (42 tokens):
"You are a helpful customer service assistant for an e-commerce company. Be polite and professional. You can help with product information, returns, and refunds. Escalate complex issues to a human agent."

Agent Notation (16 tokens):
role:cs(ecom) polite prod+ret+refund esc:complex→human

### 4. Data Analysis (53% savings)

English (32 tokens):
"Analyze the sales data in the CSV file and create a report showing monthly revenue trends, top 5 products by revenue, and year-over-year growth percentage"

Agent Notation (15 tokens):
analyze csv.sales→rpt: rev,top5×rev,yoy%

### 5. API Integration (68% savings)

English (38 tokens):
"Create a JavaScript function that calls the Stripe API to create a customer, then create a subscription with the given price ID, and handle any errors by logging them and returning a failure response"

Agent Notation (12 tokens):
js fn→stripe: create_cust→create_sub(price_id) catch→log+ret.fail

## Compression Rules (applied in order)

1. Drop filler — remove articles (a, an, the), copulas (is, are), hedging (please, could you)
2. Apply abbreviations — replace words with standard abbreviations (function → fn, return → ret)
3. Use operators — replace verbal relationships with operators (→ for flow, | for conditions)
4. Use type annotations — replace verbose types with concise notation (list of integers → int[])
5. Comma-separate parallel operations — join steps with commas
6. Use key-value for configuration — set X to Y becomes X:Y
7. Use conditionals for branching — if/else becomes pipe notation

## Installation

npm install @agentnotation/core

### CLI

npm install -g @agentnotation/cli

## CLI Usage

anot compress "Write a Python function that takes a list"
anot expand "py fn(lst:int[])→int[]: filter even, sort desc"
anot validate "fn(x)→y"
anot lint "fn(x)→y"

## Programmatic API

```typescript
import { compress, expand, validate, lint, format, countTokens } from '@agentnotation/core';

// Compress English to Agent Notation
const result = compress('Write a Python function that takes a list');

// Expand notation back to English
const english = expand('py fn(lst:int[])→int[]: filter even, sort desc');

// Validate notation syntax
const { valid, errors } = validate('fn(x)→y');

// Lint for best practices
const diagnostics = lint('fn(x)→y');

// Format notation
const formatted = format('fn(x)→y');

// Count tokens
const { original, compressed, savings } = countTokens('py fn(lst:int[])→int[]');
```

## SDK Integration

Agent Notation provides drop-in SDK wrappers that auto-compress messages with zero code changes to your prompts.

### Anthropic SDK

```bash
npm install @agentnotation/anthropic
```

```typescript
import Anthropic from '@anthropic-ai/sdk';
import { withCompression } from '@agentnotation/anthropic';

const client = withCompression(new Anthropic());

const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a Python function...' }],
});

console.log(client._anot.getStats());
```

### OpenAI SDK

```bash
npm install @agentnotation/openai
```

```typescript
import OpenAI from 'openai';
import { withCompression } from '@agentnotation/openai';

const client = withCompression(new OpenAI());

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a Python function...' }],
});

console.log(client._anot.getStats());
```

### HTTP Proxy

For any language or SDK, use the built-in proxy:

```bash
anot proxy --port 8080
export ANTHROPIC_BASE_URL=http://localhost:8080
```

The proxy auto-detects Anthropic (/v1/messages) and OpenAI (/v1/chat/completions) requests.
Check stats at GET /anot/stats.

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| ANOT_ENABLED | true | Enable/disable compression |
| ANOT_MIN_TOKENS | 30 | Skip prompts shorter than this |
| ANOT_MIN_CONFIDENCE | 0.3 | Minimum compression confidence (0-1) |
| ANOT_MIN_SAVINGS_PERCENT | 10 | Minimum savings to apply (0-100) |
| ANOT_SKIP_ROLES | (none) | Comma-separated roles to skip |
| ANOT_LOG_LEVEL | silent | silent, summary, or verbose |

### .anotrc.json

Place in your project root (auto-discovered by walking up from cwd):

```json
{
  "minTokens": 30,
  "minConfidence": 0.3,
  "minSavingsPercent": 10,
  "skipRoles": ["tool"],
  "logLevel": "summary"
}
```

## Benchmarks

| Category | English Tokens | Notation Tokens | Savings |
|----------|---------------|-----------------|---------|
| Code Generation | 35 | 14 | 60% |
| Data Analysis | 32 | 15 | 53% |
| System Prompt | 42 | 16 | 62% |
| RAG Query | 35 | 10 | 71% |
| API Integration | 38 | 12 | 68% |
| **Average** | **36.4** | **13.4** | **63%** |

## Links

- Website: https://agentnotation.dev
- Full Reference: https://agentnotation.dev/llms-full.txt

## License

MIT