attune/docker/distributable/packs/core/SETUP.md

Core Pack Setup Guide

This guide explains how to set up and load the Attune core pack into your database.

Overview

The core pack is Attune's built-in system pack that provides essential automation components including:

• Timer Triggers: Interval-based, cron-based, and datetime triggers
• Basic Actions: Echo, sleep, noop, and HTTP request actions
• Built-in Sensors: Interval timer sensor for time-based automation

The core pack must be loaded into the database before it can be used in rules and workflows.

Prerequisites

Before loading the core pack, ensure:

1. PostgreSQL is running and accessible
2. Database migrations are applied: sqlx migrate run
3. Python 3.8+ is installed (for the loader script)
4. Required Python packages are installed:

   pip install psycopg2-binary pyyaml
   

Loading Methods

Method 1: Python Loader Script (Recommended)

The Python loader script reads the pack YAML files and creates database entries automatically.

Usage:

# From the project root
python3 scripts/load_core_pack.py

# With custom database URL
python3 scripts/load_core_pack.py --database-url "postgresql://user:pass@localhost:5432/attune"

# With custom pack directory
python3 scripts/load_core_pack.py --pack-dir ./packs

What it does:

• Reads pack.yaml for pack metadata
• Loads all trigger definitions from triggers/*.yaml
• Loads all action definitions from actions/*.yaml
• Loads all sensor definitions from sensors/*.yaml
• Creates or updates database entries (idempotent)
• Uses transactions (all-or-nothing)

Output:

============================================================
Core Pack Loader
============================================================

→ Loading pack metadata...
✓ Pack 'core' loaded (ID: 1)

→ Loading triggers...
  ✓ Trigger 'core.intervaltimer' (ID: 1)
  ✓ Trigger 'core.crontimer' (ID: 2)
  ✓ Trigger 'core.datetimetimer' (ID: 3)

→ Loading actions...
  ✓ Action 'core.echo' (ID: 1)
  ✓ Action 'core.sleep' (ID: 2)
  ✓ Action 'core.noop' (ID: 3)
  ✓ Action 'core.http_request' (ID: 4)

→ Loading sensors...
  ✓ Sensor 'core.interval_timer_sensor' (ID: 1)

============================================================
✓ Core pack loaded successfully!
============================================================
  Pack ID: 1
  Triggers: 3
  Actions: 4
  Sensors: 1

Method 2: SQL Seed Script

For simpler setups or CI/CD, you can use the SQL seed script directly.

Usage:

psql $DATABASE_URL -f scripts/seed_core_pack.sql

Note: The SQL script may not include all pack metadata and is less flexible than the Python loader.

Method 3: CLI (Future)

Once the CLI pack management commands are fully implemented:

attune pack register ./packs/core

Verification

After loading, verify the core pack is available:

Using CLI

# List all packs
attune pack list

# Show core pack details
attune pack show core

# List core pack actions
attune action list --pack core

# List core pack triggers
attune trigger list --pack core

Using API

# Get pack info
curl http://localhost:8080/api/v1/packs/core | jq

# List actions
curl http://localhost:8080/api/v1/packs/core/actions | jq

# List triggers
curl http://localhost:8080/api/v1/packs/core/triggers | jq

Using Database

-- Check pack exists
SELECT * FROM attune.pack WHERE ref = 'core';

-- Count components
SELECT 
    (SELECT COUNT(*) FROM attune.trigger WHERE pack_ref = 'core') as triggers,
    (SELECT COUNT(*) FROM attune.action WHERE pack_ref = 'core') as actions,
    (SELECT COUNT(*) FROM attune.sensor WHERE pack_ref = 'core') as sensors;

Testing the Core Pack

1. Test Actions Directly

Test actions using environment variables:

# Test echo action
export ATTUNE_ACTION_MESSAGE="Hello, Attune!"
export ATTUNE_ACTION_UPPERCASE=false
./packs/core/actions/echo.sh

# Test sleep action
export ATTUNE_ACTION_SECONDS=2
export ATTUNE_ACTION_MESSAGE="Sleeping..."
./packs/core/actions/sleep.sh

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

2. Run Pack Test Suite

# Run comprehensive test suite
./packs/core/test_core_pack.sh

3. Create a Test Rule

Create a simple rule to test the core pack integration:

# Create a rule that echoes every 10 seconds
attune rule create \
  --name "test_timer_echo" \
  --trigger "core.intervaltimer" \
  --trigger-config '{"unit":"seconds","interval":10}' \
  --action "core.echo" \
  --action-params '{"message":"Timer triggered!"}' \
  --enabled

Updating the Core Pack

To update the core pack after making changes:

1. Edit the relevant YAML files in packs/core/
2. Re-run the loader script:

   python3 scripts/load_core_pack.py
   

3. The loader will update existing entries (upsert)

Troubleshooting

"Failed to connect to database"

• Verify PostgreSQL is running: pg_isready
• Check DATABASE_URL environment variable
• Test connection: psql $DATABASE_URL -c "SELECT 1"

"pack.yaml not found"

• Ensure you're running from the project root
• Check the --pack-dir argument points to the correct directory
• Verify packs/core/pack.yaml exists

"ModuleNotFoundError: No module named 'psycopg2'"

pip install psycopg2-binary pyyaml

"Pack loaded but not visible in API"

• Restart the API service to reload pack data
• Check pack is enabled: SELECT enabled FROM attune.pack WHERE ref = 'core'

Actions not executing

• Verify action scripts are executable: chmod +x packs/core/actions/*.sh
• Check worker service is running and can access the packs directory
• Verify runtime configuration is correct

Development Workflow

When developing new core pack components:

1. Add new action:

   • Create actions/new_action.yaml with metadata
   • Create actions/new_action.sh (or .py) with implementation
   • Make script executable: chmod +x actions/new_action.sh
   • Test locally: export ATTUNE_ACTION_*=... && ./actions/new_action.sh
   • Load into database: python3 scripts/load_core_pack.py

2. Add new trigger:

   • Create triggers/new_trigger.yaml with metadata
   • Load into database: python3 scripts/load_core_pack.py
   • Create sensor if needed

3. Add new sensor:

   • Create sensors/new_sensor.yaml with metadata
   • Create sensors/new_sensor.py with implementation
   • Load into database: python3 scripts/load_core_pack.py
   • Restart sensor service

Environment Variables

The loader script supports the following environment variables:

• DATABASE_URL - PostgreSQL connection string

  • Default: postgresql://postgres:postgres@localhost:5432/attune
  • Example: postgresql://user:pass@db.example.com:5432/attune

• ATTUNE_PACKS_DIR - Base directory for packs

  • Default: ./packs
  • Example: /opt/attune/packs

CI/CD Integration

For automated deployments:

# Example GitHub Actions workflow
- name: Load Core Pack
  run: |
    python3 scripts/load_core_pack.py \
      --database-url "${{ secrets.DATABASE_URL }}"
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

Next Steps

After loading the core pack:

1. Create your first rule using core triggers and actions
2. Enable sensors to start generating events
3. Monitor executions via the API or Web UI
4. Explore pack documentation in README.md

Additional Resources

• Pack README: packs/core/README.md - Comprehensive component documentation
• Testing Guide: packs/core/TESTING.md - Testing procedures
• API Documentation: docs/api-packs.md - Pack management API
• Action Development: docs/action-development.md - Creating custom actions

Support

If you encounter issues:

1. Check this troubleshooting section
2. Review logs from services (api, executor, worker, sensor)
3. Verify database state with SQL queries
4. File an issue with detailed error messages and logs

---

Last Updated: 2025-01-20
Core Pack Version: 1.0.0