LLM Spec Sheet
Copy-paste ready specifications for teaching LLMs how to use Tauq (.tqn) and TauQ Query (.tqq).
v0.2.0 LLM Optimized Copy-Paste Ready
Complete Reference (.tqn + .tqq)
# TAUQ COMPLETE REFERENCE - LLM OPTIMIZED
## QUICK START
### .tqn Files (Static Notation)
- Space-delimited, human-readable data format
- About 49% fewer tokens than minified JSON (up to 55% on flat tables)
- Define schemas once with !def, reuse with !use
- Use for: configs, static data, API responses
### .tqq Files (Pre-processor)
- Line directives (!set, !emit, !run, !pipe, !import, !json, !read,
!env) that generate .tqn
- Safe mode by default; --unsafe runs commands from an allowlist
- Use for: generated data, command output, environment-specific configs
---
# TAUQ NOTATION (.tqn) - LLM SPEC SHEET v0.2.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: # to the end of the 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
Rows written directly after a !def use that schema.
### Schema Usage (!use)
Apply a schema to rows inside an array. Put --- after the !def lines
so the key-value data that follows isn't read as rows:
!def User id name email age active
---
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
A field typed with another schema (address:Address) takes an object
written as positional values in braces:
```tauq
!def Address street city state zip
!def Person id name age address:Address
---
people [
!use Person
1 Alice 30 { "123 Main St" Springfield IL 62701 }
2 Bob 25 { "456 Oak Ave" Portland OR 97201 }
]
```
## KEY RULES
1. **Schemas First**: Put all !def lines at the top, then a --- line before key-value data
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**: # starts a comment that runs to the end of the line
## TOKEN EFFICIENCY
Tauq uses about 49% fewer tokens than minified JSON across the benchmark
datasets (up to 55% on flat tables) 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.2.0
## WHAT IS TQQ?
TQQ is a line-based pre-processor that generates Tauq notation.
- File extension: .tqq
- Output: Tauq notation (.tqn), which tauq then parses
- A line that starts with a TQQ directive (!set, !emit, !run, !pipe,
!import, !json, !read, !env) is processed; every other line passes
through unchanged, including !def and !use
- Blank lines and lines starting with # are dropped
- Use case: build Tauq from command output, scripts, JSON files and
Unix pipelines
## SAFETY
- Safe mode is the default. In safe mode every directive except !set
is rejected with an error.
- Run trusted files with --unsafe:
tauq exec file.tqq --unsafe
- Only these programs may run: sh bash zsh dash python3 python node ruby
perl jq yq echo cat head tail sort uniq grep awk sed curl wget true
false test expr
- Commands run without a shell. For pipes, globs, $(...) or redirects,
call sh -c '...'
- Child processes get a cleared environment plus the !set variables
(PATH, HOME, SHELL and library-path variables can't be set)
## DIRECTIVES
### !set KEY value
Sets a variable that later commands receive as an environment variable.
Surrounding quotes are stripped. It is not substituted into text.
!set ENV "production"
### !emit command args...
Runs a command and inserts its stdout.
!emit echo "status ok"
!emit sh -c 'echo "build_date \"$(date +%Y-%m-%d)\""'
### !run program { ... }
Runs the block with the program and inserts its stdout. The block ends
at a line that contains only }.
!run python3 {
for i in range(1, 4):
print(f'item_{i} "Item {i}"')
}
### !pipe command
Sends all output generated ABOVE this line to the command's stdin and
replaces that output with the command's stdout. Lines after !pipe are
not piped.
Carol 95
Alice 50
!pipe sort -k 2 -nr
Block form: !pipe program { ... } runs the block with the accumulated
output on stdin.
### !import file
Processes another file with the same rules and inserts its output.
### !json file
Reads a JSON file and inserts it converted to Tauq.
### !read file
Inserts the file's contents as one quoted string. It must be alone on
its line, so the string can't share a line with a key.
### !env VAR
Inserts an environment variable of the tauq process as a quoted string,
alone on its line.
## COMPLETE EXAMPLES
### Example 1: Records From a Script
```tqq
!run python3 {
print("!def User id name role")
users = [("Alice", "admin"), ("Bob", "user")]
for i, (name, role) in enumerate(users, 1):
print(i, name, role)
}
```
### Example 2: Environment-Based Config
```tqq
!set ENV "production"
app_name MyApp
!run python3 {
import os
prod = os.environ.get("ENV") == "production"
print("debug", "false" if prod else "true")
print("log_level", "error" if prod else "debug")
}
```
### Example 3: Build Metadata
```tqq
!emit sh -c 'echo "built \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""'
!emit sh -c 'echo "host \"$(hostname)\""'
```
### Example 4: Filter Rows With a Pipe
```tqq
!def User id name role
!use User
1 Alice admin
2 Bob user
3 Carol admin
!pipe grep -E "^!|admin"
```
The ^! pattern keeps the !def and !use lines.
### Example 5: JSON File to Tauq
```tqq
!json ./data/users.json
```
## KEY RULES
1. **Line Directives**: A directive is a whole line starting with !
2. **Safe By Default**: Pass --unsafe to run anything except !set
3. **Allowlist**: Only listed programs run; use sh -c for shell syntax
4. **Valid Output**: Each command's output is checked on its own and
must parse as Tauq; a script that prints schema rows should print
the !def line too
5. **Pipe Scope**: !pipe replaces everything generated above it
6. **Variables**: !set values reach commands as environment variables,
not as text substitution
7. **Comments**: # lines and blank lines are dropped
## PROCESSING
Process .tqq files to .tqn:
```bash
tauq build input.tqq -o output.tqn --unsafe
```
Or straight to JSON:
```bash
tauq exec input.tqq -o output.json --unsafe
```
Leave out --unsafe if the file only uses !set.
## WHEN TO USE TQQ
- Generate Tauq from command output or scripts
- Environment-specific configs
- Convert JSON files to Tauq
- Filter or sort generated rows with Unix tools
---
## WORKFLOW
1. **Static Data**: Write .tqn directly
```bash
tauq build data.tqn -o data.json
```
2. **Generated Data**: Write a .tqq file
```bash
tauq build template.tqq -o generated.tqn --unsafe
tauq build generated.tqn -o final.json
```
3. **Validate**: Check .tqn syntax
```bash
tauq validate input.tqn
```
4. **Prettify**: Rewrite .tqn readably (rebuilt from the parsed data,
so comments and schema names are not kept)
```bash
tauq prettify input.tqn
```
## COMMON PATTERNS
### Pattern 1: Config With an Environment Switch
```tqq
!set ENV "production"
!run sh {
if [ "$ENV" = production ]; then echo "timeout 60"; else echo "timeout 30"; fi
echo "retries 3"
}
```
### Pattern 2: Records From a Script
```tqq
!run python3 {
print("!def Record id name")
for i, name in enumerate(["Alice", "Bob"], 1):
print(i, name)
}
```
### Pattern 3: Sort Output
```tqq
Alice 50
Bob 20
Carol 95
!pipe sort -k 2 -nr
```
## 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. **Separate Schemas From Data**: After the !def lines, add --- before
key-value data
5. **Nested Objects**: Use proper indentation for readability
6. **Boolean Values**: `true` and `false` (lowercase)
7. **Null Values**: `null` (lowercase)
8. **TQQ Needs --unsafe**: for every directive except !set
## VERSION INFO
- Tauq v0.2.0
- Compared against TOON spec v3.0
- Tokenizer: tiktoken's cl100k_base (OpenAI's GPT-4 tokenizer) .tqn Spec (Static Notation)
# TAUQ NOTATION (.tqn) - LLM SPEC SHEET v0.2.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: # to the end of the 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
Rows written directly after a !def use that schema.
### Schema Usage (!use)
Apply a schema to rows inside an array. Put --- after the !def lines
so the key-value data that follows isn't read as rows:
!def User id name email age active
---
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
A field typed with another schema (address:Address) takes an object
written as positional values in braces:
```tauq
!def Address street city state zip
!def Person id name age address:Address
---
people [
!use Person
1 Alice 30 { "123 Main St" Springfield IL 62701 }
2 Bob 25 { "456 Oak Ave" Portland OR 97201 }
]
```
## KEY RULES
1. **Schemas First**: Put all !def lines at the top, then a --- line before key-value data
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**: # starts a comment that runs to the end of the line
## TOKEN EFFICIENCY
Tauq uses about 49% fewer tokens than minified JSON across the benchmark
datasets (up to 55% on flat tables) 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
``` .tqq Spec (Dynamic Pre-processor)
# TAUQ QUERY (.tqq) - LLM SPEC SHEET v0.2.0
## WHAT IS TQQ?
TQQ is a line-based pre-processor that generates Tauq notation.
- File extension: .tqq
- Output: Tauq notation (.tqn), which tauq then parses
- A line that starts with a TQQ directive (!set, !emit, !run, !pipe,
!import, !json, !read, !env) is processed; every other line passes
through unchanged, including !def and !use
- Blank lines and lines starting with # are dropped
- Use case: build Tauq from command output, scripts, JSON files and
Unix pipelines
## SAFETY
- Safe mode is the default. In safe mode every directive except !set
is rejected with an error.
- Run trusted files with --unsafe:
tauq exec file.tqq --unsafe
- Only these programs may run: sh bash zsh dash python3 python node ruby
perl jq yq echo cat head tail sort uniq grep awk sed curl wget true
false test expr
- Commands run without a shell. For pipes, globs, $(...) or redirects,
call sh -c '...'
- Child processes get a cleared environment plus the !set variables
(PATH, HOME, SHELL and library-path variables can't be set)
## DIRECTIVES
### !set KEY value
Sets a variable that later commands receive as an environment variable.
Surrounding quotes are stripped. It is not substituted into text.
!set ENV "production"
### !emit command args...
Runs a command and inserts its stdout.
!emit echo "status ok"
!emit sh -c 'echo "build_date \"$(date +%Y-%m-%d)\""'
### !run program { ... }
Runs the block with the program and inserts its stdout. The block ends
at a line that contains only }.
!run python3 {
for i in range(1, 4):
print(f'item_{i} "Item {i}"')
}
### !pipe command
Sends all output generated ABOVE this line to the command's stdin and
replaces that output with the command's stdout. Lines after !pipe are
not piped.
Carol 95
Alice 50
!pipe sort -k 2 -nr
Block form: !pipe program { ... } runs the block with the accumulated
output on stdin.
### !import file
Processes another file with the same rules and inserts its output.
### !json file
Reads a JSON file and inserts it converted to Tauq.
### !read file
Inserts the file's contents as one quoted string. It must be alone on
its line, so the string can't share a line with a key.
### !env VAR
Inserts an environment variable of the tauq process as a quoted string,
alone on its line.
## COMPLETE EXAMPLES
### Example 1: Records From a Script
```tqq
!run python3 {
print("!def User id name role")
users = [("Alice", "admin"), ("Bob", "user")]
for i, (name, role) in enumerate(users, 1):
print(i, name, role)
}
```
### Example 2: Environment-Based Config
```tqq
!set ENV "production"
app_name MyApp
!run python3 {
import os
prod = os.environ.get("ENV") == "production"
print("debug", "false" if prod else "true")
print("log_level", "error" if prod else "debug")
}
```
### Example 3: Build Metadata
```tqq
!emit sh -c 'echo "built \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""'
!emit sh -c 'echo "host \"$(hostname)\""'
```
### Example 4: Filter Rows With a Pipe
```tqq
!def User id name role
!use User
1 Alice admin
2 Bob user
3 Carol admin
!pipe grep -E "^!|admin"
```
The ^! pattern keeps the !def and !use lines.
### Example 5: JSON File to Tauq
```tqq
!json ./data/users.json
```
## KEY RULES
1. **Line Directives**: A directive is a whole line starting with !
2. **Safe By Default**: Pass --unsafe to run anything except !set
3. **Allowlist**: Only listed programs run; use sh -c for shell syntax
4. **Valid Output**: Each command's output is checked on its own and
must parse as Tauq; a script that prints schema rows should print
the !def line too
5. **Pipe Scope**: !pipe replaces everything generated above it
6. **Variables**: !set values reach commands as environment variables,
not as text substitution
7. **Comments**: # lines and blank lines are dropped
## PROCESSING
Process .tqq files to .tqn:
```bash
tauq build input.tqq -o output.tqn --unsafe
```
Or straight to JSON:
```bash
tauq exec input.tqq -o output.json --unsafe
```
Leave out --unsafe if the file only uses !set.
## WHEN TO USE TQQ
- Generate Tauq from command output or scripts
- Environment-specific configs
- Convert JSON files to Tauq
- Filter or sort generated rows with Unix tools 💡 How to Use This Spec
For LLMs: Copy one of the specs above and paste it into your LLM conversation to teach it Tauq syntax.
Complete Reference: Use when you need both .tqn and .tqq capabilities.
.tqn Only: Use for static data notation (configs, API responses, data files).
.tqq Only: Use for dynamic generation (templates, loops, conditionals).
All specs are optimized for LLM comprehension with clear examples, consistent formatting, and complete syntax coverage.