attune/packs/core/README.md

Attune Core Pack

The Core Pack is the foundational system pack for Attune, providing essential automation components including timer triggers, HTTP utilities, and basic shell actions.

Overview

The core pack is automatically installed with Attune and provides the building blocks for creating automation workflows. It includes:

• Timer Triggers: Interval-based, cron-based, and one-shot datetime timers
• HTTP Actions: Make HTTP requests to external APIs
• Shell Actions: Execute basic shell commands (echo, sleep, noop)
• Built-in Sensors: System sensors for monitoring time-based events

Components

Actions

core.echo

Outputs a message to stdout.

Parameters:

• message (string, required): Message to echo
• uppercase (boolean, optional): Convert message to uppercase

Example:

action: core.echo
parameters:
  message: "Hello, Attune!"
  uppercase: false

---

core.sleep

Pauses execution for a specified duration.

Parameters:

• seconds (integer, required): Number of seconds to sleep (0-3600)
• message (string, optional): Optional message to display before sleeping

Example:

action: core.sleep
parameters:
  seconds: 30
  message: "Waiting 30 seconds..."

---

core.noop

Does nothing - useful for testing and placeholder workflows.

Parameters:

• message (string, optional): Optional message to log
• exit_code (integer, optional): Exit code to return (default: 0)

Example:

action: core.noop
parameters:
  message: "Testing workflow structure"

---

core.http_request

Make HTTP requests to external APIs with full control over headers, authentication, and request body.

Parameters:

• url (string, required): URL to send the request to
• method (string, optional): HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• headers (object, optional): HTTP headers as key-value pairs
• body (string, optional): Request body for POST/PUT/PATCH
• json_body (object, optional): JSON request body (alternative to body)
• query_params (object, optional): URL query parameters
• timeout (integer, optional): Request timeout in seconds (default: 30)
• verify_ssl (boolean, optional): Verify SSL certificates (default: true)
• auth_type (string, optional): Authentication type (none, basic, bearer)
• auth_username (string, optional): Username for basic auth
• auth_password (string, secret, optional): Password for basic auth
• auth_token (string, secret, optional): Bearer token
• follow_redirects (boolean, optional): Follow HTTP redirects (default: true)
• max_redirects (integer, optional): Maximum redirects to follow (default: 10)

Output:

• status_code (integer): HTTP status code
• headers (object): Response headers
• body (string): Response body as text
• json (object): Parsed JSON response (if applicable)
• elapsed_ms (integer): Request duration in milliseconds
• url (string): Final URL after redirects
• success (boolean): Whether request was successful (2xx status)

Example:

action: core.http_request
parameters:
  url: "https://api.example.com/users"
  method: "POST"
  json_body:
    name: "John Doe"
    email: "john@example.com"
  headers:
    Content-Type: "application/json"
  auth_type: "bearer"
  auth_token: "${secret:api_token}"

---

Triggers

core.intervaltimer

Fires at regular intervals based on time unit and interval.

Parameters:

• unit (string, required): Time unit (seconds, minutes, hours)
• interval (integer, required): Number of time units between triggers

Payload:

• type: "interval"
• interval_seconds: Total interval in seconds
• fired_at: ISO 8601 timestamp
• execution_count: Number of times fired
• sensor_ref: Reference to the sensor

Example:

trigger: core.intervaltimer
config:
  unit: "minutes"
  interval: 5

---

core.crontimer

Fires based on cron schedule expressions.

Parameters:

• expression (string, required): Cron expression (6 fields: second minute hour day month weekday)
• timezone (string, optional): Timezone (default: UTC)
• description (string, optional): Human-readable schedule description

Payload:

• type: "cron"
• fired_at: ISO 8601 timestamp
• scheduled_at: When trigger was scheduled to fire
• expression: The cron expression
• timezone: Timezone used
• next_fire_at: Next scheduled fire time
• execution_count: Number of times fired
• sensor_ref: Reference to the sensor

Cron Format:

┌───────── second (0-59)
│ ┌─────── minute (0-59)
│ │ ┌───── hour (0-23)
│ │ │ ┌─── day of month (1-31)
│ │ │ │ ┌─ month (1-12)
│ │ │ │ │ ┌ day of week (0-6, 0=Sunday)
│ │ │ │ │ │
* * * * * *

Examples:

• 0 0 * * * * - Every hour
• 0 0 0 * * * - Every day at midnight
• 0 */15 * * * * - Every 15 minutes
• 0 30 8 * * 1-5 - 8:30 AM on weekdays

---

core.datetimetimer

Fires once at a specific date and time.

Parameters:

• fire_at (string, required): ISO 8601 timestamp when timer should fire
• timezone (string, optional): Timezone (default: UTC)
• description (string, optional): Human-readable description

Payload:

• type: "one_shot"
• fire_at: Scheduled fire time
• fired_at: Actual fire time
• timezone: Timezone used
• delay_ms: Delay between scheduled and actual fire time
• sensor_ref: Reference to the sensor

Example:

trigger: core.datetimetimer
config:
  fire_at: "2024-12-31T23:59:59Z"
  description: "New Year's countdown"

---

Sensors

core.interval_timer_sensor

Built-in sensor that monitors time and fires interval timer triggers.

Configuration:

• check_interval_seconds (integer, optional): How often to check triggers (default: 1)

This sensor automatically runs as part of the Attune sensor service and manages all interval timer trigger instances.

---

Configuration

The core pack supports the following configuration options:

# config.yaml
packs:
  core:
    max_action_timeout: 300        # Maximum action timeout in seconds
    enable_debug_logging: false    # Enable debug logging

Dependencies

Python Dependencies

• requests>=2.28.0 - For HTTP request action
• croniter>=1.4.0 - For cron timer parsing (future)

Runtime Dependencies

• Shell (bash/sh) - For shell-based actions
• Python 3.8+ - For Python-based actions and sensors

Installation

The core pack is automatically installed with Attune. No manual installation is required.

To verify the core pack is loaded:

# Using CLI
attune pack list | grep core

# Using API
curl http://localhost:8080/api/v1/packs/core

Usage Examples

Example 1: Echo Every 10 Seconds

Create a rule that echoes "Hello, World!" every 10 seconds:

ref: core.hello_world_rule
trigger: core.intervaltimer
trigger_config:
  unit: "seconds"
  interval: 10
action: core.echo
action_params:
  message: "Hello, World!"
  uppercase: false

Example 2: HTTP Health Check Every 5 Minutes

Monitor an API endpoint every 5 minutes:

ref: core.health_check_rule
trigger: core.intervaltimer
trigger_config:
  unit: "minutes"
  interval: 5
action: core.http_request
action_params:
  url: "https://api.example.com/health"
  method: "GET"
  timeout: 10

Example 3: Daily Report at Midnight

Generate a report every day at midnight:

ref: core.daily_report_rule
trigger: core.crontimer
trigger_config:
  expression: "0 0 0 * * *"
  timezone: "UTC"
  description: "Daily at midnight"
action: core.http_request
action_params:
  url: "https://api.example.com/reports/generate"
  method: "POST"

Example 4: One-Time Reminder

Set a one-time reminder for a specific date and time:

ref: core.meeting_reminder
trigger: core.datetimetimer
trigger_config:
  fire_at: "2024-06-15T14:00:00Z"
  description: "Team meeting reminder"
action: core.echo
action_params:
  message: "Team meeting starts in 15 minutes!"

Development

Adding New Actions

1. Create action metadata file: actions/<action_name>.yaml
2. Create action implementation: actions/<action_name>.sh or actions/<action_name>.py
3. Make script executable: chmod +x actions/<action_name>.sh
4. Update pack manifest if needed
5. Test the action

Testing Actions Locally

Test actions directly by setting environment variables:

# Test echo action
export ATTUNE_ACTION_MESSAGE="Test message"
export ATTUNE_ACTION_UPPERCASE=true
./actions/echo.sh

# Test HTTP request action
export ATTUNE_ACTION_URL="https://httpbin.org/get"
export ATTUNE_ACTION_METHOD="GET"
python3 actions/http_request.py

Contributing

The core pack is part of the Attune project. Contributions are welcome!

1. Follow the existing code style and structure
2. Add tests for new actions/sensors
3. Update documentation
4. Submit a pull request

License

The core pack is licensed under the same license as Attune.

Support

• Documentation: https://docs.attune.io/packs/core
• Issues: https://github.com/attune-io/attune/issues
• Discussions: https://github.com/attune-io/attune/discussions