attune-system/attune
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documenting action spec

Browse Source
This commit is contained in:
David Culbreth
2026-02-09 00:30:48 -06:00
parent a74e13fa0b
commit 588b319fec
38 changed files with 3050 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
docs/QUICKREF-output-formats.md Normal file
View File

@@ -0,0 +1,179 @@
# Quick Reference: Action Output Formats
## TL;DR
Actions can specify how their stdout should be parsed:
- `text` (default): No parsing, raw stdout only
- `json`: Parse last line as JSON
- `yaml`: Parse entire output as YAML
- `jsonl`: Parse each line as JSON, return array
## Action Definition
```yaml
name: my_action
output_format: json # text | json | yaml | jsonl
output_schema:
type: object # Use 'array' for jsonl
properties:
result: { type: string }
```
## Format Behaviors
| Format | Parses | Result | Best For |
|--------|--------|--------|----------|
| `text` | Nothing | `null` | Simple messages, logs |
| `json` | Last line | Object/Value | API responses, single results |
| `yaml` | Entire stdout | Object/Value | Configs, nested data |
| `jsonl` | Each line | Array | Lists, streaming, batches |
## Examples
### Text (no parsing)
```bash
echo "Hello, World!"
# Result: null (stdout captured separately)
```
### JSON (last line)
```bash
echo "Processing..."
echo '{"status": 200, "data": "success"}'
# Result: {"status": 200, "data": "success"}
```
### YAML (entire output)
```bash
cat <<EOF
version: 1.0
settings:
enabled: true
timeout: 30
EOF
# Result: {"version": "1.0", "settings": {...}}
```
### JSONL (each line → array)
```bash
echo '{"id": 1, "name": "Alice"}'
echo '{"id": 2, "name": "Bob"}'
echo '{"id": 3, "name": "Charlie"}'
# Result: [{"id": 1, ...}, {"id": 2, ...}, {"id": 3, ...}]
```
## Action Script Templates
### Bash + JSON
```bash
#!/bin/bash
result=$(do_work)
echo "{\"result\": \"$result\", \"status\": \"ok\"}"
```
### Python + JSON
```python
#!/usr/bin/env python3
import json
result = do_work()
print(json.dumps({"result": result, "status": "ok"}))
```
### Bash + JSONL
```bash
#!/bin/bash
for item in $(ls); do
size=$(stat -f%z "$item")
echo "{\"name\": \"$item\", \"size\": $size}"
done
```
### Python + JSONL
```python
#!/usr/bin/env python3
import json
for item in get_items():
print(json.dumps({"id": item.id, "value": item.value}))
```
## Common Patterns
### Informational + Result (JSON)
```bash
echo "Starting process..." >&2 # Log to stderr
echo "Processing 100 items..." >&2
echo '{"processed": 100, "errors": 0}' # JSON on last line
```
### Mixed Output (JSONL)
```bash
echo "Scanning directory..." >&2 # Non-JSON ignored
echo '{"file": "a.txt", "size": 1024}' # Valid JSON
echo "Found 2 files" >&2 # Non-JSON ignored
echo '{"file": "b.txt", "size": 2048}' # Valid JSON
```
## Execution Result Structure
```json
{
"exit_code": 0,
"succeeded": true,
"duration_ms": 142,
"stdout": "raw output here",
"stderr": "logs here",
"data": { /* parsed result based on output_format */ }
}
```
## Best Practices
✅ **DO**
- Use `text` for simple logging/messages
- Use `json` for structured single results
- Use `jsonl` for lists and batches
- Write one JSON object per line (no pretty-print)
- Log to stderr, output to stdout
- Use non-zero exit codes for failures
❌ **DON'T**
- Mix error messages in stdout (use stderr)
- Pretty-print JSON across multiple lines
- Assume parsing will always succeed
- Use `jsonl` without `type: array` in schema
## Troubleshooting
**No result parsed?**
- Check exit code is 0
- Verify JSON is on last line (`json`)
- Ensure one JSON per line (`jsonl`)
- Check for syntax errors in output
- Parsing failures don't cause execution failure
**JSONL returning empty array?**
- Check each line is valid JSON
- Ensure no trailing empty lines
- Invalid lines are silently skipped
**Result is null but expected data?**
- Verify `output_format` matches output
- Check stdout contains expected format
- Parsing is best-effort (no errors thrown)
## Database
```sql
-- Check action output format
SELECT ref, output_format FROM action WHERE ref = 'core.http_request';
-- Update action output format
UPDATE action SET output_format = 'jsonl' WHERE ref = 'mypack.myaction';
```
## See Also
- [Full Documentation](action-output-formats.md)
- [Pack Structure](pack-structure.md)
- [Parameter Delivery](parameter-delivery.md)
- [Execution System](execution-system.md)

1174
docs/action-development-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

459
docs/action-output-formats.md Normal file
View File

@@ -0,0 +1,459 @@
# Action Output Formats
## Overview
Attune actions can specify how their output should be parsed and stored in the execution result. This allows actions to produce structured data (JSON, YAML, JSON Lines) or plain text output, and have it automatically parsed and stored in the `execution.result` field.
## Output Format Types
### `text` (Default)
**Use Case**: Simple actions that produce human-readable output without structured data.
**Behavior**:
- No parsing is performed on stdout
- Full stdout content is captured in `execution.stdout`
- `execution.result` field is `null`
**Example Action**:
```yaml
name: echo
output_format: text
```
**Example Output**:
```
Hello, World!
```
**Execution Result**:
```json
{
"exit_code": 0,
"succeeded": true,
"stdout": "Hello, World!",
"data": null
}
```
---
### `json`
**Use Case**: Actions that produce a single JSON object or value as their final output.
**Behavior**:
- Parses the **last line** of stdout as JSON
- Stores parsed JSON in `execution.result`
- Full stdout still available in `execution.stdout`
- If parsing fails, `result` is `null` (no error)
**Example Action**:
```yaml
name: http_request
output_format: json
output_schema:
type: object
properties:
status_code:
type: integer
body:
type: string
elapsed_ms:
type: integer
```
**Example Output**:
```
Connecting to example.com...
Request sent
{"status_code": 200, "body": "{\"message\":\"ok\"}", "elapsed_ms": 142}
```
**Execution Result**:
```json
{
"exit_code": 0,
"succeeded": true,
"stdout": "Connecting to example.com...\nRequest sent\n{...}",
"data": {
"status_code": 200,
"body": "{\"message\":\"ok\"}",
"elapsed_ms": 142
}
}
```
---
### `yaml`
**Use Case**: Actions that produce YAML-formatted output, common in configuration management and infrastructure tools.
**Behavior**:
- Parses **entire stdout** as YAML
- Stores parsed data in `execution.result`
- Full stdout still available in `execution.stdout`
- If parsing fails, `result` is `null` (no error)
**Example Action**:
```yaml
name: get_config
output_format: yaml
output_schema:
type: object
properties:
version:
type: string
settings:
type: object
```
**Example Output**:
```yaml
version: "1.2.3"
settings:
enabled: true
max_retries: 3
timeout: 30
```
**Execution Result**:
```json
{
"exit_code": 0,
"succeeded": true,
"stdout": "version: \"1.2.3\"\nsettings:\n enabled: true\n...",
"data": {
"version": "1.2.3",
"settings": {
"enabled": true,
"max_retries": 3,
"timeout": 30
}
}
}
```
---
### `jsonl` (JSON Lines)
**Use Case**: Actions that produce multiple records or streaming results, where each line is a separate JSON object.
**Behavior**:
- Parses **each line** of stdout as a separate JSON object
- Collects all parsed objects into a JSON array
- Stores array in `execution.result`
- Full stdout still available in `execution.stdout`
- Invalid JSON lines are silently skipped
- If no valid JSON lines found, `result` is `null`
**Important**: When using `jsonl`, the `output_schema` root type **must be `array`**.
**Example Action**:
```yaml
name: list_users
output_format: jsonl
output_schema:
type: array
items:
type: object
properties:
id:
type: integer
username:
type: string
email:
type: string
```
**Example Output**:
```
{"id": 1, "username": "alice", "email": "alice@example.com"}
{"id": 2, "username": "bob", "email": "bob@example.com"}
{"id": 3, "username": "charlie", "email": "charlie@example.com"}
```
**Execution Result**:
```json
{
"exit_code": 0,
"succeeded": true,
"stdout": "{\"id\": 1, ...}\n{\"id\": 2, ...}\n{\"id\": 3, ...}",
"data": [
{"id": 1, "username": "alice", "email": "alice@example.com"},
{"id": 2, "username": "bob", "email": "bob@example.com"},
{"id": 3, "username": "charlie", "email": "charlie@example.com"}
]
}
```
**Benefits**:
- Memory efficient for large datasets (streaming)
- Easy to process line-by-line
- Resilient to partial failures (invalid lines skipped)
- Compatible with standard JSONL tools and libraries
---
## Choosing an Output Format
| Format | Best For | Parsing | Result Type |
|--------|----------|---------|-------------|
| `text` | Simple messages, logs, human output | None | `null` |
| `json` | Single structured result | Last line only | Object/Value |
| `yaml` | Configuration, complex nested data | Entire output | Object/Value |
| `jsonl` | Lists, streaming, multiple records | Each line | Array |
---
## Action Definition Examples
### Text Output Action
```yaml
name: echo
ref: core.echo
output_format: text
entry_point: echo.sh
parameters:
type: object
properties:
message:
type: string
```
### JSON Output Action
```yaml
name: http_request
ref: core.http_request
output_format: json
entry_point: http_request.sh
output_schema:
type: object
properties:
status_code:
type: integer
headers:
type: object
body:
type: string
```
### JSONL Output Action
```yaml
name: list_files
ref: custom.list_files
output_format: jsonl
entry_point: list_files.sh
output_schema:
type: array
items:
type: object
properties:
path:
type: string
size:
type: integer
modified:
type: string
```
---
## Writing Actions with Structured Output
### JSON Output (Bash)
```bash
#!/bin/bash
# Action script that produces JSON output
# Do work...
result=$(curl -s https://api.example.com/data)
status=$?
# Output JSON on last line
echo "{\"status\": $status, \"data\": \"$result\"}"
```
### JSON Output (Python)
```python
#!/usr/bin/env python3
import json
import sys
# Do work...
result = {"count": 42, "items": ["a", "b", "c"]}
# Output JSON on last line
print(json.dumps(result))
```
### JSONL Output (Bash)
```bash
#!/bin/bash
# Action script that produces JSONL output
# Process items and output one JSON object per line
for item in $(ls -1 /path/to/files); do
size=$(stat -f%z "$item")
echo "{\"name\": \"$item\", \"size\": $size}"
done
```
### JSONL Output (Python)
```python
#!/usr/bin/env python3
import json
import os
# Process items and output one JSON object per line
for filename in os.listdir('/path/to/files'):
info = os.stat(filename)
record = {
"name": filename,
"size": info.st_size,
"modified": info.st_mtime
}
print(json.dumps(record))
```
---
## Error Handling
### Parsing Failures
If output parsing fails:
- The action execution is still considered successful (if exit code is 0)
- `execution.result` is set to `null`
- Full stdout is still captured in `execution.stdout`
- No error is logged (parsing is best-effort)
**Example**: Action has `output_format: json` but produces invalid JSON:
```json
{
"exit_code": 0,
"succeeded": true,
"stdout": "Not valid JSON!",
"data": null
}
```
### Mixed Output
For `json` and `jsonl` formats, you can still include informational output:
**JSON** - Only last line is parsed:
```
Starting process...
Processing 100 items...
Done!
{"processed": 100, "errors": 0}
```
**JSONL** - Only valid JSON lines are parsed:
```
Starting scan...
{"file": "a.txt", "size": 1024}
{"file": "b.txt", "size": 2048}
Scan complete
```
---
## Output Schema Validation
While the `output_schema` field is used to document expected output structure, Attune does **not** currently validate action output against the schema. The schema serves as:
1. **Documentation** for action consumers
2. **Type hints** for workflow parameter mapping
3. **API documentation** generation
4. **Future validation** (planned feature)
---
## Best Practices
### 1. Choose the Right Format
- Use `text` for simple actions without structured output
- Use `json` for single-result APIs or calculations
- Use `yaml` when working with configuration management tools
- Use `jsonl` for lists, batches, or streaming results
### 2. JSON/JSONL: One JSON Per Line
```bash
# Good - Each JSON on its own line
echo '{"id": 1, "name": "Alice"}'
echo '{"id": 2, "name": "Bob"}'
# Bad - Pretty-printed JSON spans multiple lines
echo '{
"id": 1,
"name": "Alice"
}'
```
### 3. Informational Output
- Add logging/progress messages **before** the final JSON line
- For JSONL, non-JSON lines are silently ignored
### 4. Error Messages
- Write errors to **stderr**, not stdout
- Stdout should contain only the structured output
- Use non-zero exit codes for failures
```bash
# Good
if [[ $status -ne 0 ]]; then
echo "Error: Failed to connect" >&2
exit 1
fi
echo '{"success": true}'
# Bad - mixes error in stdout
if [[ $status -ne 0 ]]; then
echo "Error: Failed to connect"
echo '{"success": false}'
fi
```
### 5. Always Flush Output
```python
# Python - ensure output is written immediately
import sys
print(json.dumps(result))
sys.stdout.flush()
```
```bash
# Bash - automatic, but can force with
echo '{"result": "data"}'
sync
```
---
## Database Schema
The `output_format` field is stored in the `action` table:
```sql
CREATE TABLE action (
-- ... other columns ...
output_format TEXT NOT NULL DEFAULT 'text'
CHECK (output_format IN ('text', 'json', 'yaml', 'jsonl')),
-- ... other columns ...
);
```
Default value is `'text'` for backward compatibility.
---
## Related Documentation
- [Action Structure](pack-structure.md#actions)
- [Parameter Delivery](parameter-delivery.md)
- [Execution Results](execution-system.md#results)
- [Output Schema](json-schema.md)

39
docs/packs/pack-structure.md
View File

@@ -91,7 +91,6 @@ conf_schema:
default: 300
minimum: 1
maximum: 3600
required: []
config:
max_action_timeout: 300
@@ -123,8 +122,8 @@ runtime_deps:
Action metadata files define the parameters, output schema, and execution details for actions.
**Required Fields:**
- `name` (string): Action name (matches filename)
- `ref` (string): Full action reference (e.g., "core.echo")
- `label` (string): Human-readable action name
- `description` (string): Action description
- `runner_type` (string): Execution runtime (shell, python, nodejs, docker)
- `entry_point` (string): Script filename to execute
@@ -142,28 +141,28 @@ Action metadata files define the parameters, output schema, and execution detail
**Example:**
```yaml
name: echo
ref: core.echo
label: "Echo"
description: "Echo a message to stdout"
enabled: true
runner_type: shell
entry_point: echo.sh
# Parameter delivery (optional, defaults to env/dotenv)
parameter_delivery: env
parameter_format: dotenv
# Parameter delivery (optional, defaults to stdin/json)
parameter_delivery: stdin
parameter_format: json
parameters:
message:
type: string
description: "Message to echo"
required: true
default: "Hello, World!"
uppercase:
type: boolean
description: "Convert message to uppercase"
required: false
default: false
type: object
properties:
message:
type: string
description: "Message to echo"
default: "Hello, World!"
uppercase:
type: boolean
description: "Convert message to uppercase"
default: false
output_schema:
type: object
@@ -316,8 +315,8 @@ if __name__ == "__main__":
Sensor metadata files define sensors that monitor for events and fire triggers.
**Required Fields:**
- `name` (string): Sensor name
- `ref` (string): Full sensor reference (e.g., "core.interval_timer_sensor")
- `label` (string): Human-readable sensor name
- `description` (string): Sensor description
- `runner_type` (string): Execution runtime (python, nodejs)
- `entry_point` (string): Script filename to execute
@@ -333,8 +332,8 @@ Sensor metadata files define sensors that monitor for events and fire triggers.
**Example:**
```yaml
name: interval_timer_sensor
ref: core.interval_timer_sensor
label: "Interval Timer Sensor"
description: "Monitors time and fires interval timer triggers"
enabled: true
runner_type: python
@@ -407,8 +406,8 @@ if __name__ == "__main__":
Trigger metadata files define event types that sensors can fire.
**Required Fields:**
- `name` (string): Trigger name
- `ref` (string): Full trigger reference (e.g., "core.intervaltimer")
- `label` (string): Human-readable trigger name
- `description` (string): Trigger description
- `type` (string): Trigger type (interval, cron, one_shot, webhook, custom)
@@ -422,8 +421,8 @@ Trigger metadata files define event types that sensors can fire.
**Example:**
```yaml
name: intervaltimer
ref: core.intervaltimer
label: "Interval Timer"
description: "Fires at regular intervals"
enabled: true
type: interval