Humanize Fireworks AI Output in Perl: An On-Call Handoff Note Linter + 5 Free Tools (2026)

#!/usr/bin/env perl
# handoff_lint.pl: ask Fireworks AI for an on-call handoff note, or lint one you already have.
#   perl handoff_lint.pl --draft "db failover 02:10 UTC, replica lag ok, cert renew pending"
#   perl handoff_lint.pl samples/robotic.txt
#   perl handoff_lint.pl --json - < note.txt
# Exit codes: 0 = hand it over, 1 = rewrite before the next shift reads it, 2 = request or input failed.
# Core Perl (HTTP::Tiny, JSON::PP); HTTPS additionally needs IO::Socket::SSL + Net::SSLeay.
use strict;
use warnings;
use utf8;
use HTTP::Tiny;
use JSON::PP;

my $MAX_WORDS  = 180;
my $MAX_HEDGES = 2;

my $PREAMBLE = qr/\A\s*(?:sure|certainly|absolutely|of course|great question|here(?:'s| is| are))\b/i;
my $FILLER   = qr/\b(?:rest assured|everything is under control|no need to worry|seamless(?:ly)?|robust|proactive(?:ly)?|leverag(?:e|ed|ing)|comprehensive|holistic|as an ai|delve)\b/i;
my $HEDGE    = qr/\b(?:it seems|it appears|appears to be|might potentially|could possibly|likely|presumably|probably)\b/i;
my $RELDAY   = qr/\b(?:last night|earlier today|this morning|yesterday|a while ago|recently)\b/i;
my $OPENLINE = qr/^\s*(?:[-*]\s*)?(?:\*\*)?(?:open|still open|watch|unresolved|next shift)\b/im;
my $SIGNOFF  = qr/(?:let me know if you have any questions|hope this helps|feel free to reach out|best regards)\W*\z/i;
my $ZONE     = qr/\s?(?:UTC|GMT|Z\b|[ECMP][SD]?T\b|[+-]\d\d:?\d\d)/;
my $HHMM     = qr/(?:[01]?\d|2[0-3]):[0-5]\d(?:\s?[ap]\.?m\.?)?/i;
# a time or a range ("03:12-03:20", "23:40 to 00:25"); the zone may follow the whole span
my $CLOCK    = qr/(?<![+\-\d:])$HHMM(?:\s?(?:-|–|to)\s?$HHMM)?/i;

sub lint {
    my ($text) = @_;
    my $t = $text // '';
    $t =~ s/\A\s+|\s+\z//g;
    return ('empty note') if $t eq '';

    my @found;
    push @found, 'model preamble (Sure / Here is / Certainly)' if $t =~ $PREAMBLE;
    push @found, 'reassurance or marketing filler'             if $t =~ $FILLER;

    my $hedges = () = $t =~ /$HEDGE/g;
    push @found, "$hedges hedges (say what you checked instead)" if $hedges > $MAX_HEDGES;

    my $bare = 0;
    while ($t =~ /($CLOCK)/g) {
        my $after = substr($t, pos($t), 8);
        $bare++ unless $after =~ /\A$ZONE/;
    }
    push @found, "$bare clock time(s) with no timezone" if $bare;

    push @found, 'relative time words (last night / earlier today)' if $t =~ $RELDAY;
    push @found, 'no Open / Watch line for the next shift'          unless $t =~ $OPENLINE;

    my $words = () = $t =~ /\S+/g;
    push @found, "$words words (keep it under $MAX_WORDS)" if $words > $MAX_WORDS;

    push @found, 'chatbot sign-off at the end' if $t =~ $SIGNOFF;
    return @found;
}

sub give_up {
    print STDERR "handoff_lint: $_[0]\n";
    exit 2;
}

sub draft {
    my ($notes) = @_;
    my $key   = $ENV{FIREWORKS_API_KEY} or give_up('FIREWORKS_API_KEY is not set');
    my $base  = $ENV{FIREWORKS_BASE_URL} || 'https://api.fireworks.ai/inference';
    my $model = $ENV{FIREWORKS_MODEL}    || 'accounts/fireworks/models/kimi-k2-instruct-0905';
    $base =~ s{/+\z}{};

    my $payload = {
        model      => $model,
        max_tokens => 350,
        messages   => [
            { role => 'system',
              content => 'You write on-call handoff notes for the engineer starting the next shift. '
                       . 'Plain text, under 150 words. Every clock time gets a timezone. '
                       . 'End with an "Open:" line listing what is still unresolved. No greeting, no sign-off.' },
            { role => 'user', content => "Shift notes: $notes" },
        ],
    };

    my $http = HTTP::Tiny->new(timeout => 30, verify_SSL => 1, agent => 'handoff-lint/1.0');
    my $res  = $http->post("$base/v1/chat/completions", {
        headers => { 'Authorization' => "Bearer $key", 'Content-Type' => 'application/json' },
        content => encode_json($payload),
    });

    if ($res->{status} == 599) {
        my $why = $res->{content} // 'unknown'; $why =~ s/\s+/ /g;
        give_up('request failed: ' . substr($why, 0, 160));
    }
    give_up("HTTP $res->{status}: " . substr($res->{content} // '', 0, 200)) unless $res->{success};

    my $data = eval { decode_json($res->{content}) } or give_up('response was not JSON');
    my $text = eval { $data->{choices}[0]{message}{content} };
    give_up('no choices[0].message.content in the response') unless defined $text && $text =~ /\S/;
    return $text;
}

sub main {
    my @args = @_;
    my $json = grep { $_ eq '--json' } @args;
    @args = grep { $_ ne '--json' } @args;

    my ($source, $text);
    if (@args >= 2 && $args[0] eq '--draft') {
        ($source, $text) = ('fireworks', draft($args[1]));
    } elsif (@args && $args[0] eq '-') {
        ($source, $text) = ('stdin', do { local $/; <STDIN> });
    } elsif (@args) {
        open(my $fh, '<:encoding(UTF-8)', $args[0]) or give_up("cannot read $args[0]: $!");
        ($source, $text) = ($args[0], do { local $/; <$fh> });
    } else {
        give_up('usage: perl handoff_lint.pl [--json] (--draft "notes" | file | -)');
    }

    my @problems = lint($text);
    binmode(STDOUT, ':encoding(UTF-8)');
    if ($json) {
        print JSON::PP->new->canonical->encode(
            { source => $source, ok => (@problems ? JSON::PP::false : JSON::PP::true), problems => \@problems }), "\n";
    } else {
        print "$text\n---\n" if $source eq 'fireworks';
        print @problems ? join('', map { "$source: $_\n" } @problems) : "ok: $source\n";
    }
    exit(@problems ? 1 : 0);
}

main(@ARGV) unless $ENV{HANDOFF_LINT_NO_MAIN};
1;

use strict;
use warnings;
use Test::More;
BEGIN { $ENV{HANDOFF_LINT_NO_MAIN} = 1 }
require './handoff_lint.pl';

my $clean = "Primary DB failed over to replica-2 at 02:10 UTC; writes back at 02:14 UTC.\n"
          . "Checked: replication lag under 1s since 02:30 UTC.\n"
          . "Open: TLS cert on api-gw expires Fri 18:00 UTC, renewal PR #812 waiting on review.";
is_deeply([ main::lint($clean) ], [], 'clean note passes');

my @p = main::lint("Sure! Here is the handoff. Rest assured everything is under control.");
ok((grep { /preamble/ } @p), 'preamble caught');
ok((grep { /filler/ } @p),   'filler caught');
ok((grep { /Open/ } @p),     'missing Open line caught');

@p = main::lint("Deploy rolled back at 14:05 and again at 3:40 pm.\nOpen: none");
ok((grep { /2 clock time/ } @p), 'two bare clock times counted');

@p = main::lint("Rollback at 14:05 UTC, retry at 15:10 +02:00.\nOpen: none");
is_deeply(\@p, [], 'zoned times pass');

@p = main::lint("It seems the queue is likely fine. It appears probably stable.\nOpen: none");
ok((grep { /hedges/ } @p), 'hedge stack caught');

@p = main::lint("Disk alert fired last night, cleared.\nOpen: none\nLet me know if you have any questions!");
ok((grep { /relative time/ } @p), 'relative day words caught');
ok((grep { /sign-off/ } @p),      'sign-off caught');

@p = main::lint(join(' ', ('word') x 200) . "\nOpen: none");
ok((grep { /201 words|200 words|words \(keep/ } @p), 'length cap');

@p = main::lint("Queue lag 03:12-03:20 UTC, again 23:40 to 00:25 UTC.\nOpen: none");
is_deeply(\@p, [], 'zoned ranges pass');

is_deeply([ main::lint("   ") ], ['empty note'], 'empty note');
done_testing;

"""Stand-in for the Fireworks chat completions endpoint. Python stdlib only.
usage: python3 mock_fireworks.py MODE PORT    (MODE: robotic | clean | nozone | error | empty)
Each request appends one line to mock.log so the test run can show what the client sent."""
import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer

MODE, PORT = sys.argv[1], int(sys.argv[2])

ANSWERS = {
    "robotic": "Certainly! Rest assured the cache cluster is stable. It seems the evictions were "
               "likely transient and probably resolved earlier today.\nHope this helps!",
    "clean": "Cache cluster evictions spiked 03:12-03:20 UTC after a key-size regression.\n"
             "Rolled back build 9921 at 03:24 UTC; hit rate back to 97%.\n"
             "Open: add a key-size alert (ticket OPS-318).",
    "nozone": "Cache evictions spiked at 03:12 and settled by 03:20 after the rollback.\n"
              "Open: key-size alert, ticket OPS-318.",
    "empty": "",
}


class FakeFireworks(BaseHTTPRequestHandler):
    def do_POST(self):
        size = self.headers.get("Content-Length", "0")
        raw_body = self.rfile.read(int(size))
        req = json.loads(raw_body or b"{}")
        messages = req.get("messages") or []
        auth = self.headers.get("Authorization", "")
        record = {"path": self.path,
                  "bearer": "present" if auth.startswith("Bearer ") else "missing",
                  "type": self.headers.get("Content-Type")}
        for key in ("model", "max_tokens"):
            record[key] = req.get(key)
        record["roles"] = ",".join(str(msg.get("role")) for msg in messages)
        with open("mock.log", "a") as log:
            log.write(" ".join("%s=%s" % kv for kv in record.items()) + "\n")

        if self.path != "/inference/v1/chat/completions":
            self.answer(404, {"error": {"message": "unknown path " + self.path}})
        elif MODE == "error":
            self.answer(401, {"error": {"object": "error", "type": "invalid_request_error",
                                        "message": "The API key you provided is invalid."}})
        else:
            reply = {"content": ANSWERS[MODE], "role": "assistant"}
            self.answer(200, {"object": "chat.completion", "id": "mock-fw-1", "model": req.get("model"),
                              "choices": [{"message": reply, "finish_reason": "stop", "index": 0}]})

    def answer(self, status, doc):
        payload = json.dumps(doc).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Length", "%d" % len(payload))
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(payload)

    def log_message(self, fmt, *args):
        pass


if __name__ == "__main__":
    HTTPServer(("127.0.0.1", PORT), FakeFireworks).serve_forever()

# HTTPS needs IO::Socket::SSL + Net::SSLeay (apt: libio-socket-ssl-perl)
perl handoff_lint.pl samples/clean.txt
perl handoff_lint.pl --json - < note.txt

export FIREWORKS_API_KEY=...
perl handoff_lint.pl --draft "payments queue backed up 23:40-00:25 UTC, rolled back deploy"

python3 mock_fireworks.py robotic 8811 &
FIREWORKS_API_KEY=test-key FIREWORKS_BASE_URL=http://127.0.0.1:8811/inference \
  perl handoff_lint.pl --draft "cache evictions spiked"

prove -v t/lint.t