Choose and describe tools for an AI agent

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// Node 18+, ESM. A tool registry: definition and implementation side by side.
async function apiverve(id, params) {
  const url = `https://api.apiverve.com/v1/${id}?${new URLSearchParams(params)}`;
  const res = await fetch(url, { headers: { 'x-api-key': process.env.APIVERVE_API_KEY } });
  const body = await res.json();
  if (body.status !== 'ok') throw new Error(`${id} ${res.status}: ${body.error}`);
  return body.data;
}

export const TOOLS = {
  get_local_time: {
    definition: {
      name: 'get_local_time',
      description:
        'Current local time and date in a city, from a live clock. Returns city, region, timezone, time24 (HH:MM:SS) and date (YYYY-MM-DD). ' +
        'If the result has ambiguous=true, the city name matches places in different timezones: ask the user which one, listing the candidates. Do not guess.',
      strict: true,
      input_schema: {
        type: 'object',
        additionalProperties: false,
        properties: {
          city: { type: 'string', description: 'City name only, e.g. "Springfield"' },
          region: { type: 'string', description: 'State or province if the user gave one, e.g. "Illinois". Empty string if not.' },
          country_code: { type: 'string', description: 'ISO 3166-1 alpha-2 code if known, e.g. "US". Empty string if not.' },
        },
        required: ['city', 'region', 'country_code'],
      },
    },
    async run({ city, region, country_code }) {
      const data = await apiverve('worldtime', { city });           // only declared params go out
      let matches = data.foundCities;
      if (country_code) matches = matches.filter((c) => c.iso2 === country_code.toUpperCase());
      if (region) matches = matches.filter((c) => (c.province ?? '').toLowerCase() === region.toLowerCase());
      if (!matches.length) return { found: false, message: `No match for ${city} with those filters.` };

      const zones = new Set(matches.map((c) => c.timezone));
      if (zones.size > 1) {
        return {
          ambiguous: true,
          candidates: matches.slice(0, 6).map((c) => ({ city: c.city, region: c.province, country: c.iso2, timezone: c.timezone })),
        };
      }
      const c = matches[0];
      return { city: c.city, region: c.province, timezone: c.timezone, time24: c.time24, date: c.date };
    },
  },

  convert_currency: {
    definition: {
      name: 'convert_currency',
      description:
        'Convert an amount between two currencies at the live market rate. Returns convertedValue, rate, and date/lastUpdated for the rate. ' +
        'Use this for any money conversion; do not multiply rates yourself.',
      strict: true,
      input_schema: {
        type: 'object',
        additionalProperties: false,
        properties: {
          amount: { type: 'number', description: 'Amount in the source currency, e.g. 250' },
          from: { type: 'string', description: 'ISO 4217 code, e.g. "USD"' },
          to: { type: 'string', description: 'ISO 4217 code, e.g. "JPY"' },
        },
        required: ['amount', 'from', 'to'],
      },
    },
    async run({ amount, from, to }) {
      const d = await apiverve('currencyconverter', { value: amount, from: from.toUpperCase(), to: to.toUpperCase() });
      return { from: d.from, to: d.to, amount: d.value, convertedValue: d.convertedValue, rate: d.rate, date: d.date, lastUpdated: d.lastUpdated };
    },
  },
};

export const definitions = Object.values(TOOLS).map((t) => t.definition);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# Python 3.9+. A tool registry: definition and implementation side by side.
import os

import requests


def apiverve(api_id, params):
    r = requests.get(
        f"https://api.apiverve.com/v1/{api_id}",
        params=params,
        headers={"x-api-key": os.environ["APIVERVE_API_KEY"]},
        timeout=15,
    )
    body = r.json()
    if body.get("status") != "ok":
        raise RuntimeError(f"{api_id} {r.status_code}: {body.get('error')}")
    return body["data"]


def get_local_time(city, region="", country_code=""):
    matches = apiverve("worldtime", {"city": city})["foundCities"]
    if country_code:
        matches = [c for c in matches if c.get("iso2") == country_code.upper()]
    if region:
        matches = [c for c in matches if (c.get("province") or "").lower() == region.lower()]
    if not matches:
        return {"found": False, "message": f"No match for {city} with those filters."}
    if len({c["timezone"] for c in matches}) > 1:
        return {
            "ambiguous": True,
            "candidates": [
                {"city": c["city"], "region": c.get("province"), "country": c.get("iso2"), "timezone": c["timezone"]}
                for c in matches[:6]
            ],
        }
    c = matches[0]
    return {"city": c["city"], "region": c.get("province"), "timezone": c["timezone"], "time24": c["time24"], "date": c["date"]}


def convert_currency(amount, from_, to):
    d = apiverve("currencyconverter", {"value": amount, "from": from_.upper(), "to": to.upper()})
    keys = ("from", "to", "value", "convertedValue", "rate", "date", "lastUpdated")
    return {k: d.get(k) for k in keys}


TOOLS = {
    "get_local_time": {
        "run": lambda a: get_local_time(a["city"], a.get("region", ""), a.get("country_code", "")),
        "definition": {
            "name": "get_local_time",
            "description": (
                "Current local time and date in a city, from a live clock. Returns city, region, timezone, "
                "time24 (HH:MM:SS) and date (YYYY-MM-DD). If the result has ambiguous=true, the city name matches "
                "places in different timezones: ask the user which one, listing the candidates. Do not guess."
            ),
            "strict": True,
            "input_schema": {
                "type": "object",
                "additionalProperties": False,
                "properties": {
                    "city": {"type": "string", "description": 'City name only, e.g. "Springfield"'},
                    "region": {"type": "string", "description": 'State or province if given, e.g. "Illinois". Empty string if not.'},
                    "country_code": {"type": "string", "description": 'ISO 3166-1 alpha-2 code if known, e.g. "US". Empty string if not.'},
                },
                "required": ["city", "region", "country_code"],
            },
        },
    },
    "convert_currency": {
        "run": lambda a: convert_currency(a["amount"], a["from"], a["to"]),
        "definition": {
            "name": "convert_currency",
            "description": (
                "Convert an amount between two currencies at the live market rate. Returns convertedValue, rate, "
                "and date/lastUpdated for the rate. Use this for any money conversion; do not multiply rates yourself."
            ),
            "strict": True,
            "input_schema": {
                "type": "object",
                "additionalProperties": False,
                "properties": {
                    "amount": {"type": "number", "description": "Amount in the source currency, e.g. 250"},
                    "from": {"type": "string", "description": 'ISO 4217 code, e.g. "USD"'},
                    "to": {"type": "string", "description": 'ISO 4217 code, e.g. "JPY"'},
                },
                "required": ["amount", "from", "to"],
            },
        },
    },
}

DEFINITIONS = [t["definition"] for t in TOOLS.values()]