Implementation Guide

Customize Prompts

Modify system prompts to match your organization's tone and terminology:

// In pipeline JSON, locate the stage:
{
  "id": "parse-intake",
  "config": {
    "system_prompt": "You are supporting a financial counsellor at [YOUR ORG]...",
    "prompt": "..."
  }
}

Model Selection

Swap models based on your requirements:

// For cost optimization:
"model": "claude-3-haiku-20240307"

// For maximum quality:
"model": "claude-opus-4-20250514"

// For different research provider:
"provider": "perplexity",
"model": "sonar"  // vs "sonar-pro"

Output Formats

Customize the JSON output structure:

// In compile-output stage:
{
  "id": "compile-output",
  "component_type": "json_transform",
  "config": {
    "jmespath_expression": "{
      our_custom_field: action_plan,
      documents: {
        briefing: counsellor_briefing,
        handout: client_materials
      }
    }"
  }
}

Research Focus Areas

Add or modify research queries:

// Add specific needs input:
"input_schema": {
  "specific_needs": {
    "type": "array",
    "items": { "type": "string" },
    "description": "e.g., 'childcare assistance'"
  }
}

// Reference in prompt:
"prompt": "...Also search for:
  {{input.specific_needs | join(', ')}}"

REST API

Run pipelines via HTTP:

# Start the API server
fm serve --port 8080

# Execute pipeline
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": "fc-crisis-to-action",
    "input": {
      "contact_content": "...",
      "state": "VIC"
    }
  }'

Python SDK

Integrate into Python applications:

from flowmason import Pipeline

# Load and run pipeline
pipeline = Pipeline.from_file(
    "pipelines/fc-crisis-to-action.json"
)

result = pipeline.run({
    "contact_content": client_message,
    "state": "VIC",
    "suburb": "Melbourne"
})

# Access outputs
action_plan = result["action_plan"]
briefing = result["counsellor_briefing"]

Webhook Triggers

Trigger from form submissions or emails:

# Configure webhook endpoint
fm webhook create \
  --pipeline fc-crisis-to-action \
  --path /intake \
  --secret YOUR_WEBHOOK_SECRET

# Incoming webhook transforms to input:
{
  "contact_content": "{{body.message}}",
  "contact_method": "form",
  "state": "{{body.state}}"
}

Case Management Integration

Push results to your CMS:

# Add output webhook stage:
{
  "id": "push-to-cms",
  "component_type": "http_request",
  "config": {
    "url": "https://your-cms.com/api/cases",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{env.CMS_TOKEN}}"
    },
    "body": {
      "risk_score": "{{upstream.risk.score}}",
      "action_plan": "{{upstream.plan}}"
    }
  }
}

Test Scenarios

Include these scenarios in your test suite:

• 1 Standard intake - Basic case with debt and housing concerns
• 2 Crisis scenario - Self-harm indicators (verify escalation)
• 3 High risk - Imminent eviction, dependents present
• 4 Low information - Minimal details provided
• 5 Follow-up - Progress tracking with partial completion

Validation Checks

# Run validation suite
fm validate pipelines/financial-counselling/

# Expected checks:
✓ All stages have valid dependencies
✓ No circular dependencies
✓ All referenced variables exist
✓ Provider configurations valid
✓ Schema validation passes

# Run with test input
fm test pipelines/fc-crisis-to-action.json \
  --scenarios tests/scenarios/

Production Checklist

• API keys stored in secure secret manager
• Crisis escalation contacts configured
• Logging level set appropriately (no PII in logs)
• Rate limiting configured for API endpoints
• Backup pipeline tested for provider failover
• CMS integration tested end-to-end
• Staff trained on reviewing AI outputs

Monitoring

# Enable execution logging
fm serve \
  --port 8080 \
  --log-level INFO \
  --metrics-port 9090

# Key metrics to monitor:
- pipeline_execution_duration_seconds
- pipeline_stage_errors_total
- crisis_escalations_total
- research_citation_completeness