LLM Spec Sheet

# TAUQ COMPLETE REFERENCE - LLM OPTIMIZED

## QUICK START

### .tqn Files (Static Notation)
- Space-delimited, human-readable data format
- 44-54% fewer tokens than JSON
- Define schemas once with !def, reuse with !use
- Use for: configs, static data, API responses

### .tqq Files (Dynamic Pre-processor)
- Generates .tqn using JavaScript
- Use {{ }} for code, {{= }} for output
- Use for: templates, dynamic data, conditionals

---

# TAUQ NOTATION (.tqn) - LLM SPEC SHEET v0.1.0

## CORE SYNTAX

### Basic Structure
- Space-delimited values (spaces are token-efficient)
- Values without spaces don't need quotes
- Quoted strings for values with spaces: "hello world"
- Comments: // single-line or /* multi-line */

### Data Types
- Strings: bareword or "quoted string"
- Numbers: 42, 3.14, -10
- Booleans: true, false
- Null: null
- Arrays: [item1 item2 item3]
- Objects: {key1 value1 key2 value2}

### Schema Definitions (!def)
Define once, use many times:

!def User id name email age active

### Schema Usage (!use)
Apply schema to data rows:

users [
  !use User
  1 Alice alice@example.com 25 true
  2 Bob bob@example.com 30 false
]

### Inline Objects
Without schema:

config {
  timeout 30
  retries 3
  debug true
}

## COMPLETE EXAMPLES

### Example 1: User List with Schema
```tauq
!def User id name email role
users [
  !use User
  1 Alice alice@example.com admin
  2 Bob bob@example.com user
  3 Carol carol@example.com user
]
```

### Example 2: Configuration File
```tauq
app_name "MyApp"
version "1.0.0"
port 8080
debug false

database {
  host localhost
  port 5432
  name myapp_db
  credentials {
    username admin
    password "secret 123"
  }
}

features [monitoring logging analytics]
```

### Example 3: API Response
```tauq
!def Product id name price stock
!def Category id name

categories [
  !use Category
  1 Electronics
  2 Books
]

products [
  !use Product
  101 Laptop 999.99 15
  102 Mouse 29.99 50
  103 "USB Cable" 9.99 100
]
```

### Example 4: Nested Data
```tauq
!def Address street city state zip
!def Person id name age

people [
  !use Person
  1 Alice 30
  2 Bob 25
]

addresses {
  alice {
    !use Address
    "123 Main St" Springfield IL 62701
  }
  bob {
    !use Address
    "456 Oak Ave" Portland OR 97201
  }
}
```

## KEY RULES

1. **Schemas First**: Define all !def schemas before using them
2. **Space Delimiters**: Use spaces between values (not commas)
3. **Quote When Needed**: Only quote strings with spaces or special chars
4. **Arrays**: Use [brackets] with space-separated items
5. **Objects**: Use {braces} with key-value pairs
6. **Schema Application**: !use applies to all following rows until next schema
7. **Nesting**: Objects and arrays can nest freely
8. **Comments**: // for single-line, /* */ for multi-line

## TOKEN EFFICIENCY

Tauq achieves 44-54% fewer tokens than JSON by:
- Using spaces instead of commas (spaces don't tokenize separately)
- Schema definitions eliminate repeated keys
- No quotes needed for simple values
- Compact syntax with minimal punctuation

## CONVERSION TO JSON

The tauq CLI converts .tqn to JSON:
```bash
tauq build input.tqn -o output.json
```

---

# TAUQ QUERY (.tqq) - LLM SPEC SHEET v0.1.0

## WHAT IS TQQ?

TQQ is a programmable pre-processor for generating Tauq notation dynamically.
- File extension: .tqq
- Outputs: .tqn (Tauq notation)
- Use case: Generate Tauq from templates, loops, conditionals

## CORE SYNTAX

### Text Passthrough
Regular text and Tauq syntax passes through unchanged:

```tqq
app_name MyApp
version 1.0.0
```

### Code Blocks
Execute code with {{ }}:

```tqq
{{ const version = "2.0.0"; }}
version {{= version }}
```

### Expressions
Output values with {{= expr }}:

```tqq
count {{= 5 + 3 }}
name {{= "Alice".toUpperCase() }}
```

### Conditionals
```tqq
{{ if (env === "production") { }}
debug false
{{ } else { }}
debug true
{{ } }}
```

### Loops
```tqq
!def User id name email
users [
  !use User
  {{ users.forEach((u, i) => { }}
  {{= i+1 }} {{= u.name }} {{= u.email }}
  {{ }); }}
]
```

### Functions
```tqq
{{ function makeConfig(env) {
  return env === "prod" ? "production" : "development";
} }}

environment {{= makeConfig("prod") }}
```

## COMPLETE EXAMPLES

### Example 1: Dynamic User List
```tqq
{{ const users = [
  {name: "Alice", email: "alice@example.com", role: "admin"},
  {name: "Bob", email: "bob@example.com", role: "user"}
]; }}

!def User id name email role
users [
  !use User
  {{ users.forEach((u, i) => { }}
  {{= i+1 }} {{= u.name }} {{= u.email }} {{= u.role }}
  {{ }); }}
]
```

### Example 2: Environment-Based Config
```tqq
{{ const env = process.env.NODE_ENV || "development"; }}
{{ const isProd = env === "production"; }}

app_name MyApp
environment {{= env }}

{{ if (isProd) { }}
debug false
log_level error
max_connections 100
{{ } else { }}
debug true
log_level debug
max_connections 10
{{ } }}

database {
  host {{= isProd ? "prod.db.com" : "localhost" }}
  port {{= isProd ? 5432 : 5433 }}
}
```

### Example 3: Generated Schema from Data
```tqq
{{ const products = [
  {id: 1, name: "Laptop", price: 999.99, stock: 5},
  {id: 2, name: "Mouse", price: 29.99, stock: 50}
]; }}

{{ const fields = Object.keys(products[0]); }}

!def Product {{= fields.join(' ') }}
products [
  !use Product
  {{ products.forEach(p => { }}
  {{= Object.values(p).join(' ') }}
  {{ }); }}
]
```

### Example 4: API Data to Tauq
```tqq
{{ const apiData = {
  users: [
    {id: 1, name: "Alice", active: true},
    {id: 2, name: "Bob", active: false}
  ],
  settings: {
    timeout: 30,
    retries: 3
  }
}; }}

!def User id name active
users [
  !use User
  {{ apiData.users.forEach(u => { }}
  {{= u.id }} {{= u.name }} {{= u.active }}
  {{ }); }}
]

settings {
  {{ Object.entries(apiData.settings).forEach(([k,v]) => { }}
  {{= k }} {{= v }}
  {{ }); }}
}
```

### Example 5: Date/Time Generation
```tqq
{{ const now = new Date(); }}
{{ const timestamp = now.toISOString(); }}
{{ const day = now.getDate(); }}

metadata {
  generated {{= timestamp }}
  day_of_month {{= day }}
  year {{= now.getFullYear() }}
}
```

## KEY RULES

1. **Code Blocks**: {{ code }} for execution
2. **Expressions**: {{= expr }} for output
3. **No Semicolons in Output**: Expressions auto-output, no ; needed
4. **JavaScript Runtime**: Full JavaScript available in {{ }} blocks
5. **Preserve Formatting**: Whitespace and indentation maintained
6. **Mix & Match**: Combine static Tauq with dynamic generation

## PROCESSING

Process .tqq files to .tqn:
```bash
tauq build input.tqq -o output.tqn
```

Then convert .tqn to JSON:
```bash
tauq build output.tqn -o final.json
```

Or chain them:
```bash
tauq build input.tqq | tauq build - -o final.json
```

## WHEN TO USE TQQ

- Generate Tauq from dynamic data sources
- Template-based configuration generation
- API response transformation
- Conditional data structures
- Bulk data generation from arrays
- Environment-specific configs

---

## WORKFLOW

1. **Static Data**: Write .tqn directly
   ```bash
   tauq build data.tqn -o data.json
   ```

2. **Dynamic Data**: Write .tqq template
   ```bash
   tauq build template.tqq -o generated.tqn
   tauq build generated.tqn -o final.json
   ```

3. **Validate**: Check syntax
   ```bash
   tauq validate input.tqn
   ```

4. **Format**: Auto-format files
   ```bash
   tauq format input.tqn
   ```

## COMMON PATTERNS

### Pattern 1: Config with Defaults
```tqq
{{ const defaults = {timeout: 30, retries: 3}; }}
{{ const custom = {timeout: 60}; }}
{{ const config = {...defaults, ...custom}; }}

{{ Object.entries(config).forEach(([k,v]) => { }}
{{= k }} {{= v }}
{{ }); }}
```

### Pattern 2: Conditional Features
```tqq
{{ const features = ["auth", "logging"]; }}
{{ if (process.env.ENABLE_ANALYTICS) features.push("analytics"); }}

features [{{= features.join(' ') }}]
```

### Pattern 3: Schema from Object
```tqq
{{ const data = [{id:1, name:"Alice"}]; }}
!def Record {{= Object.keys(data[0]).join(' ') }}
```

## GOTCHAS & TIPS

1. **Spaces Matter**: `[a b c]` not `[a, b, c]`
2. **Quote Multi-word**: `name "John Doe"` not `name John Doe`
3. **Schema Order**: Define !def before !use
4. **TQQ Output**: {{= }} includes implicit newline
5. **Nested Objects**: Use proper indentation for readability
6. **Boolean Values**: `true` and `false` (lowercase)
7. **Null Values**: `null` (lowercase)

## VERSION INFO

- Tauq v0.1.0
- Compared against TOON v2.0
- Tokenizer: tiktoken cl100k_base (GPT-4/Claude)

# TAUQ NOTATION (.tqn) - LLM SPEC SHEET v0.1.0

## CORE SYNTAX

### Basic Structure
- Space-delimited values (spaces are token-efficient)
- Values without spaces don't need quotes
- Quoted strings for values with spaces: "hello world"
- Comments: // single-line or /* multi-line */

### Data Types
- Strings: bareword or "quoted string"
- Numbers: 42, 3.14, -10
- Booleans: true, false
- Null: null
- Arrays: [item1 item2 item3]
- Objects: {key1 value1 key2 value2}

### Schema Definitions (!def)
Define once, use many times:

!def User id name email age active

### Schema Usage (!use)
Apply schema to data rows:

users [
  !use User
  1 Alice alice@example.com 25 true
  2 Bob bob@example.com 30 false
]

### Inline Objects
Without schema:

config {
  timeout 30
  retries 3
  debug true
}

## COMPLETE EXAMPLES

### Example 1: User List with Schema
```tauq
!def User id name email role
users [
  !use User
  1 Alice alice@example.com admin
  2 Bob bob@example.com user
  3 Carol carol@example.com user
]
```

### Example 2: Configuration File
```tauq
app_name "MyApp"
version "1.0.0"
port 8080
debug false

database {
  host localhost
  port 5432
  name myapp_db
  credentials {
    username admin
    password "secret 123"
  }
}

features [monitoring logging analytics]
```

### Example 3: API Response
```tauq
!def Product id name price stock
!def Category id name

categories [
  !use Category
  1 Electronics
  2 Books
]

products [
  !use Product
  101 Laptop 999.99 15
  102 Mouse 29.99 50
  103 "USB Cable" 9.99 100
]
```

### Example 4: Nested Data
```tauq
!def Address street city state zip
!def Person id name age

people [
  !use Person
  1 Alice 30
  2 Bob 25
]

addresses {
  alice {
    !use Address
    "123 Main St" Springfield IL 62701
  }
  bob {
    !use Address
    "456 Oak Ave" Portland OR 97201
  }
}
```

## KEY RULES

1. **Schemas First**: Define all !def schemas before using them
2. **Space Delimiters**: Use spaces between values (not commas)
3. **Quote When Needed**: Only quote strings with spaces or special chars
4. **Arrays**: Use [brackets] with space-separated items
5. **Objects**: Use {braces} with key-value pairs
6. **Schema Application**: !use applies to all following rows until next schema
7. **Nesting**: Objects and arrays can nest freely
8. **Comments**: // for single-line, /* */ for multi-line

## TOKEN EFFICIENCY

Tauq achieves 44-54% fewer tokens than JSON by:
- Using spaces instead of commas (spaces don't tokenize separately)
- Schema definitions eliminate repeated keys
- No quotes needed for simple values
- Compact syntax with minimal punctuation

## CONVERSION TO JSON

The tauq CLI converts .tqn to JSON:
```bash
tauq build input.tqn -o output.json
```

# TAUQ QUERY (.tqq) - LLM SPEC SHEET v0.1.0

## WHAT IS TQQ?

TQQ is a programmable pre-processor for generating Tauq notation dynamically.
- File extension: .tqq
- Outputs: .tqn (Tauq notation)
- Use case: Generate Tauq from templates, loops, conditionals

## CORE SYNTAX

### Text Passthrough
Regular text and Tauq syntax passes through unchanged:

```tqq
app_name MyApp
version 1.0.0
```

### Code Blocks
Execute code with {{ }}:

```tqq
{{ const version = "2.0.0"; }}
version {{= version }}
```

### Expressions
Output values with {{= expr }}:

```tqq
count {{= 5 + 3 }}
name {{= "Alice".toUpperCase() }}
```

### Conditionals
```tqq
{{ if (env === "production") { }}
debug false
{{ } else { }}
debug true
{{ } }}
```

### Loops
```tqq
!def User id name email
users [
  !use User
  {{ users.forEach((u, i) => { }}
  {{= i+1 }} {{= u.name }} {{= u.email }}
  {{ }); }}
]
```

### Functions
```tqq
{{ function makeConfig(env) {
  return env === "prod" ? "production" : "development";
} }}

environment {{= makeConfig("prod") }}
```

## COMPLETE EXAMPLES

### Example 1: Dynamic User List
```tqq
{{ const users = [
  {name: "Alice", email: "alice@example.com", role: "admin"},
  {name: "Bob", email: "bob@example.com", role: "user"}
]; }}

!def User id name email role
users [
  !use User
  {{ users.forEach((u, i) => { }}
  {{= i+1 }} {{= u.name }} {{= u.email }} {{= u.role }}
  {{ }); }}
]
```

### Example 2: Environment-Based Config
```tqq
{{ const env = process.env.NODE_ENV || "development"; }}
{{ const isProd = env === "production"; }}

app_name MyApp
environment {{= env }}

{{ if (isProd) { }}
debug false
log_level error
max_connections 100
{{ } else { }}
debug true
log_level debug
max_connections 10
{{ } }}

database {
  host {{= isProd ? "prod.db.com" : "localhost" }}
  port {{= isProd ? 5432 : 5433 }}
}
```

### Example 3: Generated Schema from Data
```tqq
{{ const products = [
  {id: 1, name: "Laptop", price: 999.99, stock: 5},
  {id: 2, name: "Mouse", price: 29.99, stock: 50}
]; }}

{{ const fields = Object.keys(products[0]); }}

!def Product {{= fields.join(' ') }}
products [
  !use Product
  {{ products.forEach(p => { }}
  {{= Object.values(p).join(' ') }}
  {{ }); }}
]
```

### Example 4: API Data to Tauq
```tqq
{{ const apiData = {
  users: [
    {id: 1, name: "Alice", active: true},
    {id: 2, name: "Bob", active: false}
  ],
  settings: {
    timeout: 30,
    retries: 3
  }
}; }}

!def User id name active
users [
  !use User
  {{ apiData.users.forEach(u => { }}
  {{= u.id }} {{= u.name }} {{= u.active }}
  {{ }); }}
]

settings {
  {{ Object.entries(apiData.settings).forEach(([k,v]) => { }}
  {{= k }} {{= v }}
  {{ }); }}
}
```

### Example 5: Date/Time Generation
```tqq
{{ const now = new Date(); }}
{{ const timestamp = now.toISOString(); }}
{{ const day = now.getDate(); }}

metadata {
  generated {{= timestamp }}
  day_of_month {{= day }}
  year {{= now.getFullYear() }}
}
```

## KEY RULES

1. **Code Blocks**: {{ code }} for execution
2. **Expressions**: {{= expr }} for output
3. **No Semicolons in Output**: Expressions auto-output, no ; needed
4. **JavaScript Runtime**: Full JavaScript available in {{ }} blocks
5. **Preserve Formatting**: Whitespace and indentation maintained
6. **Mix & Match**: Combine static Tauq with dynamic generation

## PROCESSING

Process .tqq files to .tqn:
```bash
tauq build input.tqq -o output.tqn
```

Then convert .tqn to JSON:
```bash
tauq build output.tqn -o final.json
```

Or chain them:
```bash
tauq build input.tqq | tauq build - -o final.json
```

## WHEN TO USE TQQ

- Generate Tauq from dynamic data sources
- Template-based configuration generation
- API response transformation
- Conditional data structures
- Bulk data generation from arrays
- Environment-specific configs