Turn a voice memo into a blog post draft

npm create adonisjs@latest memo-to-post -- --kit=api
cd memo-to-post

@fetchski:registry=https://acme.example/api/v1/sdk/npm/
//acme.example/api/v1/sdk/npm/:_authToken=fsk_acme_…

.npmrc

node ace configure @fetchski/attract-cms-adonis

# OpenRouter: your key, and the model the agent runs on
OPENROUTER_API_KEY=sk-or-v1-…
OPENROUTER_MODEL=~anthropic/claude-opus-latest

/*
|--------------------------------------------------------------------------
| Environment variables service
|--------------------------------------------------------------------------
|
| The `Env.create` method creates an instance of the Env service. The
| service validates the environment variables and also cast values
| to JavaScript data types.
|
*/

import { Env } from '@adonisjs/core/env'

export default await Env.create(new URL('../', import.meta.url), {
  // Node
  NODE_ENV: Env.schema.enum(['development', 'production', 'test'] as const),
  PORT: Env.schema.number(),
  HOST: Env.schema.string({ format: 'host' }),
  LOG_LEVEL: Env.schema.string(),

  // App
  APP_KEY: Env.schema.secret(),
  APP_URL: Env.schema.string({ format: 'url', tld: false }),

  // Session
  SESSION_DRIVER: Env.schema.enum(['cookie', 'memory', 'database'] as const),

  /*
  |----------------------------------------------------------
  | Variables for configuring @fetchski/attract-cms-adonis
  |----------------------------------------------------------
  */
  FETCHSKI_ATTRACT_SITE: Env.schema.string(),
  FETCHSKI_ATTRACT_URL: Env.schema.string({ format: 'url', tld: false }),
  FETCHSKI_ATTRACT_API_KEY: Env.schema.secret(),
  FETCHSKI_ATTRACT_SIGNING_SECRET: Env.schema.secret.optional(),

  // OpenRouter
  OPENROUTER_API_KEY: Env.schema.secret(),
  OPENROUTER_MODEL: Env.schema.string(),
})

SESSION_DRIVER=memory

# Tests fake the site and the model: placeholders only
FETCHSKI_ATTRACT_SITE=acme
FETCHSKI_ATTRACT_URL=https://acme.example
FETCHSKI_ATTRACT_API_KEY=fsk_acme_0a1b2c3d_not-a-real-secret
OPENROUTER_API_KEY=sk-or-v1-not-a-real-key
OPENROUTER_MODEL=test/fake-model

import env from '#start/env'

/**
 * The model the agents run on, and the limits every run stays inside.
 */
const openrouterConfig = {
  apiKey: env.get('OPENROUTER_API_KEY'),
  model: env.get('OPENROUTER_MODEL'),
  maxSteps: 12, // tool rounds per run, at most
  maxCostUsd: 1, // a run stops once it has spent this much
}

export default openrouterConfig

node ace make:provider openrouter --register

import { OpenRouter } from '@openrouter/agent'
import type { ApplicationService } from '@adonisjs/core/types'
import type openrouterConfig from '#config/openrouter'

export default class OpenrouterProvider {
  constructor(protected app: ApplicationService) {}

  /**
   * One OpenRouter client for the whole app. Tests swap it for a fake model.
   */
  register() {
    this.app.container.singleton(OpenRouter, () => {
      const config = this.app.config.get<typeof openrouterConfig>('openrouter')

      return new OpenRouter({ apiKey: config.apiKey.release() })
    })
  }
}

import { tool } from '@openrouter/agent'
import type { BlogImportResult, SiteClient } from '@fetchski/attract-cms-sdk'
import { z } from 'zod'

/** What the run saved, for the code around the agent (never the model's word for it). */
export interface PostWriterRun {
  draft: BlogImportResult | null
}

/**
 * The site, as the agent sees it: six tools, each one SDK call. Every
 * write is a draft; nothing here can publish, and no image is created.
 */
export function postWriterTools(site: SiteClient, run: PostWriterRun) {
  const getPostTemplate = tool({
    name: 'get_post_template',
    description:
      "The site's Markdown template for a blog post: every front matter key, and the blog's categories. Read it first.",
    inputSchema: z.object({}),
    execute: async () => {
      const template = await site.blogPosts().getBlogMarkdownTemplate()
      return { template: template.content }
    },
  })

  const listAuthors = tool({
    name: 'list_authors',
    description: "The blog's authors, by name. Credit the post to one with authorName.",
    inputSchema: z.object({}),
    execute: async () => {
      const authors = await site.authors().listAuthorsPick(['title'])
      return { authors: authors.map((author) => author.title) }
    },
  })

  const findRelatedPosts = tool({
    name: 'find_related_posts',
    description:
      'Published posts that match a few words. Link to one or two that a reader of this post would want next.',
    inputSchema: z.object({
      words: z.string().min(2).describe('A few words about the topic, e.g. "spring opening hours"'),
    }),
    execute: async ({ words }) => {
      const list = await site.blogPosts().listBlogs({ search: words, perPage: 5 })
      return { posts: list.results.map(({ title, url }) => ({ title, url })) }
    },
  })

  const findImages = tool({
    name: 'find_library_images',
    description:
      "Images already in the site's library that match a few words. Use one as featuredImage by its slug, with featuredImageAlt.",
    inputSchema: z.object({
      words: z.string().min(2).describe('What the picture should show, e.g. "storefront"'),
    }),
    execute: async ({ words }) => {
      const images = await site.fetchskiMedia().listMediaImages({ q: words, limit: 5 })
      return {
        images: images.results.map(({ slug, title, alt }) => ({ slug, title, alt })),
      }
    },
  })

  const checkPost = tool({
    name: 'check_post',
    description:
      'Check a whole post (front matter and body) against the site, without saving it. Fix every error it names, then check again.',
    inputSchema: z.object({
      markdown: z
        .string()
        .min(1)
        .describe('The whole post: front matter between --- lines, then the body'),
    }),
    execute: async ({ markdown }) => {
      const result = await site.blogPosts().validateBlogImport({ markdown })
      return { valid: result.valid, errors: result.errors.map((error) => error.message) }
    },
  })

  const saveDraft = tool({
    name: 'save_draft',
    description:
      'Save the checked post on the site as an unpublished draft. Call it once, after check_post says valid.',
    inputSchema: z.object({
      markdown: z.string().min(1).describe('The same post check_post passed'),
    }),
    execute: async ({ markdown }) => {
      if (run.draft) {
        return { error: `Already saved as "${run.draft.title}". Stop here.` }
      }
      run.draft = await site.blogPosts().importBlogPost({ markdown, publish: false, ai: true })
      return { saved: true, title: run.draft.title }
    },
  })

  return [getPostTemplate, listAuthors, findRelatedPosts, findImages, checkPost, saveDraft] as const
}

import { inject } from '@adonisjs/core'
import { maxCost, OpenRouter, stepCountIs } from '@openrouter/agent'
import { SiteClient } from '@fetchski/attract-cms-sdk'
import app from '@adonisjs/core/services/app'
import type openrouterConfig from '#config/openrouter'
import { postWriterTools, type PostWriterRun } from '#services/post_writer_tools'

const INSTRUCTIONS = `You turn a business owner's spoken notes into a blog post for their own website.

- Write in their voice: keep their words, their examples and their opinions. Tidy the
  "ums" and repeats, never their meaning.
- Use only facts from the notes. Never invent a price, a date, a name, a number or a
  promise. If the notes leave something open, leave it out and say so in your reply.
- Read the template first and follow it. Pick a category it lists. Body headings start at ##.
- Credit an author from list_authors only when the notes or the request name one.
- Link to one or two related posts in the body, by their url, only when they really fit.
- A featured image is optional: use only a library image's slug, never a web address.
- check_post, fix what it says, and check again until it is valid. Then save_draft once.
- Finish with two or three plain sentences for the editor: what the post covers, and
  anything they should check before publishing.`

export interface PostWriterResult {
  /** The saved draft, or null when the agent saved nothing. */
  draft: {
    id: string
    title: string
    /** The draft on the site, for anyone with the link, without signing in. */
    previewUrl: string | null
  } | null
  /** The agent's note to the editor, or why it saved nothing. */
  note: string
  costUsd: number
}

@inject()
export class PostWriter {
  constructor(
    protected site: SiteClient,
    protected openrouter: OpenRouter
  ) {}

  /** Has the agent write a draft post from the notes, then shares it and sends it for review. */
  async draftFrom(notes: string, author?: string): Promise<PostWriterResult> {
    const config = app.config.get<typeof openrouterConfig>('openrouter')
    const run: PostWriterRun = { draft: null }

    const result = this.openrouter.callModel({
      model: config.model,
      instructions: INSTRUCTIONS,
      input: author ? `Author: ${author}\n\nThe notes:\n\n${notes}` : `The notes:\n\n${notes}`,
      tools: postWriterTools(this.site, run),
      stopWhen: [
        stepCountIs(config.maxSteps),
        maxCost(config.maxCostUsd),
        () => run.draft !== null, // saved: the agent's work is done
      ],
    })
    const note = await result.getText()
    const usage = await result.getUsage()

    if (!run.draft) {
      return { draft: null, note: note.trim(), costUsd: usage.cost ?? 0 }
    }

    // Code, not the agent, makes the private preview link and puts the draft in the review queue.
    const shared = await this.site.blogPosts().shareBlog({ id: run.draft.id, share: true })
    await this.site.blogPosts().submitBlog({ id: run.draft.id })

    const previewUrl =
      run.draft.url && shared.aposShareKey
        ? `${run.draft.url}?${new URLSearchParams({ aposShareKey: shared.aposShareKey, aposShareId: run.draft.id })}`
        : null

    return {
      draft: { id: run.draft.id, title: run.draft.title, previewUrl },
      note: note.trim(),
      costUsd: usage.cost ?? 0,
    }
  }
}

node ace make:command post_from_notes

import { readFile } from 'node:fs/promises'
import { inject } from '@adonisjs/core'
import { args, BaseCommand, flags } from '@adonisjs/core/ace'
import type { CommandOptions } from '@adonisjs/core/types/ace'
import { PostWriter } from '#services/post_writer'

export default class PostFromNotes extends BaseCommand {
  static commandName = 'post:from-notes'
  static description =
    'Turn a voice memo transcript or rough notes into a draft blog post, ready for review'
  static options: CommandOptions = { startApp: true }

  @args.string({ description: 'The transcript or notes, as a text file' })
  declare file: string

  @flags.string({ description: 'The author to credit, as the blog names them' })
  declare author?: string

  @inject()
  async run(writer: PostWriter) {
    const text = await readFile(this.file, 'utf8')
    const notes = text.trim()
    if (notes.length < 200) {
      this.logger.error(
        `${this.file} is too short to make a post from: give it 200 characters or more`
      )
      this.exitCode = 1
      return
    }

    const { draft, note, costUsd } = await writer.draftFrom(notes, this.author)
    if (!draft) {
      this.logger.error('The agent saved no draft: nothing was written to the site')
      this.logger.log(note)
      this.exitCode = 1
      return
    }

    this.logger.success(`Draft saved and sent for review: "${draft.title}"`)
    this.logger.info(`Preview: ${draft.previewUrl ?? 'open it in the CMS, under Submitted drafts'}`)
    this.logger.info(`Cost: $${costUsd.toFixed(4)}`)
    this.logger.log(note)
  }
}

npm run format
node ace codegen
npm run lint
npm run typecheck

mkdir -p storage/notes

Okay, quick one for the blog. Starting in March we're going to open on Saturday mornings, nine to one. A lot of you told us weekdays are hard, you're at work, you can't get here before we close, so this is for you. Saturdays are walk-in only, no booking needed, first come first served. Weekday hours stay exactly the same. And if Saturdays go well we'll look at a late evening on Thursdays too, but no promises yet. Thanks for telling us what you need, honestly that's how we decide this stuff.

node ace post:from-notes storage/notes/saturday-mornings.txt --author="Jordan Lee"

[ success ] Draft saved and sent for review: "We're opening on Saturday mornings"
[ info ] Preview: https://acme.example/blog/were-opening-on-saturday-mornings?aposShareKey=…&aposShareId=…
[ info ] Cost: $0.2480
A short post announcing walk-in Saturday mornings, 9 to 1, from March. The notes give no exact start date, so add one before publishing.

import { createServer } from 'node:http'
import type { AddressInfo } from 'node:net'
import { OpenRouter } from '@openrouter/agent'

/** One answer from the model: tool calls to make, or its closing text. */
export type FakeTurn =
  | { calls: { name: string; arguments: Record<string, unknown> }[] }
  | { text: string }

/**
 * A stand-in for OpenRouter on 127.0.0.1: it answers each request with the
 * next turn, in the Responses API's own stream format, and keeps every
 * request it was sent. Nothing leaves the machine and nothing is spent.
 */
export async function fakeModel(turns: FakeTurn[]) {
  const requests: Record<string, unknown>[] = []

  const server = createServer(async (request, response) => {
    let body = ''
    for await (const chunk of request) {
      body += chunk
    }
    requests.push(JSON.parse(body) as Record<string, unknown>)

    const turn = turns[requests.length - 1] ?? { text: 'Done.' }
    const output =
      'calls' in turn
        ? turn.calls.map((call, index) => ({
            type: 'function_call',
            id: `fc_${requests.length}_${index}`,
            call_id: `call_${requests.length}_${index}`,
            name: call.name,
            arguments: JSON.stringify(call.arguments),
            status: 'completed',
          }))
        : [
            {
              type: 'message',
              id: `msg_${requests.length}`,
              role: 'assistant',
              status: 'completed',
              content: [{ type: 'output_text', text: turn.text, annotations: [] }],
            },
          ]

    const completed = {
      type: 'response.completed',
      sequence_number: 1,
      response: {
        id: `resp_${requests.length}`,
        object: 'response',
        created_at: 1,
        completed_at: 2,
        model: 'test/fake-model',
        status: 'completed',
        error: null,
        incomplete_details: null,
        instructions: null,
        metadata: {},
        parallel_tool_calls: true,
        frequency_penalty: 0,
        presence_penalty: 0,
        temperature: null,
        top_p: null,
        tools: [],
        tool_choice: 'auto',
        output,
        usage: {
          input_tokens: 1000,
          output_tokens: 200,
          total_tokens: 1200,
          cost: 0.001,
          input_tokens_details: { cached_tokens: 0 },
          output_tokens_details: { reasoning_tokens: 0 },
        },
      },
    }
    response.writeHead(200, { 'content-type': 'text/event-stream' })
    response.end(`event: response.completed\ndata: ${JSON.stringify(completed)}\n\n`)
  })

  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
  const { port } = server.address() as AddressInfo

  return {
    client: new OpenRouter({ apiKey: 'test', serverURL: `http://127.0.0.1:${port}/api/v1` }),
    requests,
    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
  }
}

import { test } from '@japa/runner'
import app from '@adonisjs/core/services/app'
import { OpenRouter } from '@openrouter/agent'
import { factories, fakeAttract } from '@fetchski/attract-cms-adonis/testing'
import { PostWriter } from '#services/post_writer'
import { fakeModel } from '#tests/helpers/fake_model'

const NOTES = 'So the big news this month is that we are opening on Sundays. '.repeat(5)
const POST = `---
title: We're open on Sundays
category: News
---

## Why Sundays

So many of you asked.
`

test.group('PostWriter', () => {
  test('checks the post, saves one draft, shares it and sends it for review', async ({
    assert,
    swap,
    cleanup,
  }) => {
    const site = fakeAttract({
      'blogPosts.getBlogMarkdownTemplate': { filename: 'post.md', content: '---\ntitle:\n---' },
      'blogPosts.validateBlogImport': { valid: true, errors: [] },
      'blogPosts.importBlogPost': factories.BlogImportResult({
        id: 'post-1:en:draft',
        title: "We're open on Sundays",
        url: 'https://acme.example/blog/open-on-sundays',
        published: false,
      }),
      'blogPosts.shareBlog': factories.Blog({ aposShareKey: 'share-key-1' }),
    })
    const model = await fakeModel([
      {
        calls: [
          { name: 'get_post_template', arguments: {} },
          { name: 'find_related_posts', arguments: { words: 'opening hours' } },
        ],
      },
      { calls: [{ name: 'check_post', arguments: { markdown: POST } }] },
      { calls: [{ name: 'save_draft', arguments: { markdown: POST } }] },
      { text: 'A short post announcing Sunday opening. Check the hours before publishing.' },
    ])
    cleanup(() => model.close())
    swap(OpenRouter, model.client)

    const writer = await app.container.make(PostWriter)
    const { draft, note } = await writer.draftFrom(NOTES, 'Jordan Lee')

    assert.equal(
      draft?.previewUrl,
      'https://acme.example/blog/open-on-sundays?aposShareKey=share-key-1&aposShareId=post-1%3Aen%3Adraft'
    )
    assert.equal(note, 'A short post announcing Sunday opening. Check the hours before publishing.')
    site.assertCalled(
      'blogPosts.importBlogPost',
      (args) => args.publish === false && args.ai === true
    )
    site.assertCalled('blogPosts.listBlogs', (args) => args.search === 'opening hours')
    site.assertCalled(
      'blogPosts.shareBlog',
      (args) => args.id === 'post-1:en:draft' && args.share === true
    )
    site.assertCalled('blogPosts.submitBlog', (args) => args.id === 'post-1:en:draft')
    site.assertNotCalled('blogPosts.publishBlog')
    assert.lengthOf(model.requests, 4)
  })

  test('a post that fails the checks is never saved', async ({ assert, swap, cleanup }) => {
    const site = fakeAttract({
      'blogPosts.validateBlogImport': {
        valid: false,
        errors: [{ message: 'Front matter needs a title.' }],
      },
    })
    const model = await fakeModel([
      { calls: [{ name: 'check_post', arguments: { markdown: '## No title' } }] },
      { text: 'The notes did not give me enough for a title.' },
    ])
    cleanup(() => model.close())
    swap(OpenRouter, model.client)

    const writer = await app.container.make(PostWriter)
    const { draft, note } = await writer.draftFrom(NOTES)

    assert.isNull(draft)
    assert.equal(note, 'The notes did not give me enough for a title.')
    site.assertNotCalled('blogPosts.importBlogPost')
    site.assertNotCalled('blogPosts.submitBlog')
  })
})

import { mkdtemp, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { test } from '@japa/runner'
import ace from '@adonisjs/core/services/ace'
import { OpenRouter } from '@openrouter/agent'
import { fakeAttract } from '@fetchski/attract-cms-adonis/testing'
import PostFromNotes from '../../commands/post_from_notes.js'
import { fakeModel } from '#tests/helpers/fake_model'

/** A notes file in a fresh temporary folder. */
async function notesFile(text: string) {
  const file = join(await mkdtemp(join(tmpdir(), 'notes-')), 'notes.txt')
  await writeFile(file, text)
  return file
}

test.group('post:from-notes', (group) => {
  group.each.setup(() => {
    ace.ui.switchMode('raw')
    return () => ace.ui.switchMode('normal')
  })

  test('notes too short to write from never reach the agent', async ({ swap, cleanup }) => {
    const site = fakeAttract()
    const model = await fakeModel([])
    cleanup(() => model.close())
    swap(OpenRouter, model.client)
    const file = await notesFile('Open Sundays.')

    const command = await ace.create(PostFromNotes, [file])
    await command.exec()

    command.assertFailed()
    command.assertLogMatches(/too short to make a post from/)
    site.assertNothingCalled()
  })

  test('the agent saving nothing fails the command, with its reason', async ({
    assert,
    swap,
    cleanup,
  }) => {
    fakeAttract()
    const model = await fakeModel([{ text: 'These notes are a shopping list, not a post.' }])
    cleanup(() => model.close())
    swap(OpenRouter, model.client)
    const file = await notesFile('Milk, eggs, bread, coffee, paper towels. '.repeat(6))

    const command = await ace.create(PostFromNotes, [file])
    await command.exec()

    command.assertFailed()
    command.assertLog('These notes are a shopping list, not a post.')
    assert.lengthOf(model.requests, 1)
  })
})

npm run format
node ace test

[ info ] loading hooks...
[ info ] generating indexes...
[ info ] codegen: created 5 file(s)
[ info ] booting application to run tests...
✔✔✔✔

 PASSED

Tests  4 passed (4)