Tutorial — your first hug

import { define_hug, file } from '@getcliqio/hug-frontend/define';
import { z } from 'zod';

export default define_hug({
    name: 'review-batch',
    title: 'Review a batch of documents',
    description:
        'Asks a reviewer to look at a batch of a company’s documents and give each one a verdict: OK, or not OK with a ' +
        'note saying why. Params: the company, and the documents (id, name, and the artifact_id of the attached file). ' +
        'The answer has one verdict per document, in order, and optional evidence.',
    params: z.object({
        company: z.string().min(1).describe('Company'),
        documents: z.array(z.object({
            id: z.string().min(1),
            name: z.string().min(1),
            artifact_id: z.string().optional().describe('The attached file to show'),
        })).min(1).max(50),
    }),
    values: (p) => z.object({
        verdicts: z.array(z.object({
            id: z.string(),
            ok: z.boolean().describe('OK'),
            note: z.string().trim().max(500).optional().describe('Why not'),
        })).length(p.documents.length, 'one verdict per document').superRefine((verdicts, ctx) => {
            verdicts.forEach((v, i) => {
                if (v.id !== p.documents[i]?.id) ctx.addIssue({ code: 'custom', path: [i, 'id'], message: 'verdicts follow the documents, in order' });
                if (!v.ok && !v.note) ctx.addIssue({ code: 'custom', path: [i, 'note'], message: 'Say what is wrong with this document' });
            });
        }).describe('Verdicts'),
        evidence: file({ accept: ['image/*', '.pdf', '.txt'], optional: true, max_bytes: 5_000_000 }).describe('Evidence'),
    }),
    summary: (v) => {
        const ok = v.verdicts.filter((x) => x.ok).length;
        return ok === v.verdicts.length ? `All ${ok} OK` : `${ok} of ${v.verdicts.length} OK`;
    },
});

import { html, mount_hug, nothing } from '@getcliqio/hug-frontend';
import '@getcliqio/hug-frontend/ui';
import review_batch from '../hug';

const CHOICES = [{ value: 'ok', label: 'OK' }, { value: 'no', label: 'Not OK', tone: 'danger' }];

mount_hug(review_batch, {
    initial: (p) => ({ verdicts: p.documents.map((d) => ({ id: d.id, ok: true })) }),
    submit: (v) => (v.verdicts.every((x) => x.ok) ? 'Approve all' : 'Send verdicts'),
    edit: ({ params, value, set, problems, hug }) => html`
        <p>Documents for <strong>${params.company}</strong></p>
        ${params.documents.map((d, i) => {
            const v = value.verdicts[i];
            const file = hug.attachments.find((a) => a.artifact_id === d.artifact_id);
            return html`<div class="doc">
                <h3>${d.name}</h3>
                ${file ? html`<cliq-attachment .ref=${file}></cliq-attachment>` : nothing}
                <cliq-choice-group label="Verdict" .value=${v.ok ? 'ok' : 'no'} .choices=${CHOICES}
                    @change=${(e) => {
                        set(`verdicts[${i}].ok`, e.detail === 'ok');
                        if (e.detail === 'ok') set(`verdicts[${i}].note`, undefined);
                    }}></cliq-choice-group>
                ${v.ok ? nothing : html`<cliq-field label="What is wrong?" multiline required
                    .value=${v.note} .problem=${problems[`verdicts[${i}].note`]}
                    @change=${(e) => set(`verdicts[${i}].note`, e.detail)}></cliq-field>`}
            </div>`;
        })}
        <cliq-file key="evidence" label="Evidence (optional)" .value=${value.evidence}
            @change=${(e) => set('evidence', e.detail)}></cliq-file>`,
});

{ "company": "ACME", "documents": [{ "id": "lease", "name": "Lease" }, { "id": "payslip", "name": "Payslip" }] }

import { describe, expect, it } from 'vitest';
import review_batch from './hug';

const PARAMS = { company: 'ACME', documents: [{ id: 'lease', name: 'Lease' }, { id: 'payslip', name: 'Payslip' }] };

describe('review-batch', () => {
    it('a rejection needs a note', () => {
        const p = review_batch.check_params(PARAMS);
        if (!p.ok) throw new Error('params');
        const missing = review_batch.check({ verdicts: [{ id: 'lease', ok: true }, { id: 'payslip', ok: false }] }, p.value);
        expect(missing).toMatchObject({ ok: false, problems: [{ path: 'verdicts[1].note' }] });
    });
});

const attachments = await ctx.attach(['documents/*']);
const documents = attachments.map((a) => ({ id: id_of(a.name), name: a.name, artifact_id: a.artifact_id }));

const answer = await ctx.ask('review-batch', {
    title: `Review ${company}'s documents`,
    params: { company, documents },
    attachments,
});
// Already checked against the definition: one verdict per document, a note for each one that isn't OK.
for (const v of answer.value.verdicts) console.log(v.id, v.ok ? 'OK' : `not OK: ${v.note}`);

phases:
  - name: review
    agent: batch-reviewer
    hug:
      name: review-batch
      channels: ["{{inputs.reviewers}}"]
      timeout: 2h

  - name: follow-up
    agent: claude-api
    role: roles/follow-up.md
    depends_on: [review]
    hug:
      name: review-batch
      channels: ["{{inputs.reviewers}}"]