Converting Natural Language to Structured Data

interface ExpenseCategory {
  id: string;
  name: string;
}

interface Currency {
  code: string;
  symbol: string;
}

export function ExpenseForm() {
  const [amount, setAmount] = useState('');
  const [currency, setCurrency] = useState('');
  const [categoryId, setCategoryId] = useState('');
  const [date, setDate] = useState('');
  const [description, setDescription] = useState('');

  const [currencies, setCurrencies] = useState<Currency[]>([]);
  const [categories, setCategories] = useState<ExpenseCategory[]>([]);

  useEffect(() => {
    fetch('/api/currencies')
      .then((r) => r.json())
      .then(setCurrencies);
    fetch('/api/expense-categories')
      .then((r) => r.json())
      .then(setCategories);
  }, []);

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    // submit to backend …
  };

  return (
    <form onSubmit={handleSubmit} style={{ display: 'grid', gap: 8 }}>
      <input
        type="number"
        name="amount"
        value={amount}
        onChange={(e) => setAmount(e.target.value)}
        placeholder="Amount"
      />

      <select
        name="currency"
        value={currency}
        onChange={(e) => setCurrency(e.target.value)}
      >
        <option value="">Select currency</option>
        {currencies.map((c) => (
          <option key={c.code} value={c.code}>
            {c.symbol} — {c.code}
          </option>
        ))}
      </select>

      <select
        name="category"
        value={categoryId}
        onChange={(e) => setCategoryId(e.target.value)}
      >
        <option value="">Select category</option>
        {categories.map((cat) => (
          <option key={cat.id} value={cat.id}>
            {cat.name}
          </option>
        ))}
      </select>

      <input
        type="date"
        name="date"
        value={date}
        onChange={(e) => setDate(e.target.value)}
      />
      <textarea
        value={description}
        name="description"
        onChange={(e) => setDescription(e.target.value)}
        placeholder="Description"
      />
      <button type="submit">Submit</button>
    </form>
  );
}

import { s } from '@hashbrownai/core';

export const ExpenseResultSuccessSchema = s.object('Parsed expense', {
  type: s.literal('Expense'),
  amount: s.number('The amount of the expense'),
  currency: s.string('ISO 4217 currency code, e.g. USD'),
  categoryId: s.string('ID of the chosen category'),
  date: s.string('ISO date YYYY-MM-DD'),
  description: s.string('Short description'),
});

export type ExpenseResultSuccess = s.infer<typeof ExpenseResultSuccessSchema>;

export const ExpenseResultParseErrorSchema = s.object('Unable to parse', {
  type: s.literal('ParseError'),
  message: s.string('Human readable error'),
});

export type ExpenseResultParseError = s.infer<
  typeof ExpenseResultParseErrorSchema
>;

export const ExpenseResultSchema = s.anyOf([
  ExpenseResultSuccessSchema, // Success branch
  ExpenseResultParseErrorSchema, // Error branch
]);

import { useTool } from '@hashbrownai/react';

export function useCategoryTool() {
  return useTool({
    name: 'listExpenseCategories',
    description: 'List valid expense categories the user can pick from',
    async handler(abortSignal) {
      const res = await fetch('/api/expense-categories', {
        signal: abortSignal,
      });
      const categories = res.json();

      return categories.map((category) => ({
        id: category.id,
        name: category.name,
      }));
    },
  });
}

import React from 'react';
import { useStructuredCompletion } from '@hashbrownai/react';
import { s } from '@hashbrownai/core';
import { ExpenseResultSchema } from './expenseSchema';
import { useCategoryTool } from './useCategoryTool';

export function ExpenseNL({ onSubmit }: { onSubmit(expense: unknown): void }) {
  const [input, setInput] = useState('');
  const categoryTool = useCategoryTool();

  const completion = useStructuredCompletion({
    model: 'gpt-4.1',
    debugName: 'expense-nl',
    input, // drives the hook reactively
    tools: [categoryTool],
    system: `
      You are an accounting assistant. Convert the user's natural language 
      statement into a JSON object that matches the provided schema.
      * The user can speak in any language. Detect and handle it.
      * Call the "listExpenseCategories" tool to pick a category ID corresponds to the user's wording. 
      * If anything is missing or ambiguous, return a ParseError instead.
    `,
    schema: ExpenseResultSchema,
  });

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    completion.reload();
  };

  useEffect(() => {
    const result = completion.output;
    if (!result) return;

    if (result.type === 'Expense') {
      onSubmit(result);
      setInput('');
    } else {
      alert(result.message);
    }
  }, [completion.output, onSubmit]);

  return (
    <form onSubmit={handleSubmit} style={{ display: 'grid', gap: 8 }}>
      <textarea
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="Describe your expense in any language…"
        rows={3}
      />
      <button
        type="submit"
        disabled={completion.isSending || completion.isReceiving}
      >
        {completion.isReceiving ? 'Parsing…' : 'Submit'}
      </button>
    </form>
  );
}