simonmichael
Draft: prototype v1 api
I'm opening this PR to 'work in public' on this API. I heavily used Claude 4 Sonnet to write this, because I am unfamiliar with the codebase, so the code is somewhat messy and not well-structured, but I will clean it up before a final merge.
But so far it works! Here is my 'financial advisor' in open-webui looking up how much I've spent on coffee for example:
That's since 2019, I don't spend that much every month hehe. I had to give it the full account name because the /accounts/{name}/balance endpoint matches exactly rather than using regex, which is a bug.
TODOs and issues to work out:
- [ ] rename to
/api/llm - [ ] add pagination to endpoints
- [ ] add query params to endpoints
- [ ] match queries in the same way that the CLI does (currently it does an exact match, not a regex-style match)
- [ ] make sure endpoints are tested
- [ ] test the openapi-v1.yaml spec?
Some open questions:
- I started doing a RESTful-style design with e.g.
/accountsendpoints, but the hledger CLI is organized aroundbalandreg, so now I'm thinking its best to mimic the CLI as closely as possible. Does that sound right? - How should we represent amounts? Right now I have this structured JSON like
{"commodity": "USD", "quantity": "1000"}. I'm not sure how much information is useful, as a human reader I just want$1000, so maybe that's what should be in the final output. - How do I test this? I'm just using restclient.el and api.http interactively right now, but a test suite will be necessary. Maybe there is a tool that can do some generative testing given the openapi-v1.yaml spec?
Very interesting!
- I'm not sure. Experimentation is good, we may need to try or provide a few different apis, at least temporarily. I'd be open to naming them to avoid prematurely signalling a preferred version. (And we probably need to save "v1" for the current API.)
- It does depend, doesn't it. Who / what / which uses cases will this new API aim to support ? Will it focus on this AI use case, or be a more general one for web apps or mobile clients ?
- hledger-web's test suite might be one way ? You can add http requests there IIRC.
Good points, I think it's best to stay focused on this AI use case for now. If it turns out that a more general API is desired, then we can expand it later. I will rename it to /api/llm for now to signify that this is specifically for LLM's to use as a tool (unless you prefer some other prefix).
Now that I have the basic working structure, I will do the experimentation to figure out what the useful API is. Once that is finished and I get some docs written, maybe we could merge this, but I don't want to merge it prematurely.
Another thought: the CLI output with -O json is also the verbose representation, which honestly I think is unusable. So maybe, if I figure out a better json representation of these datatypes, the CLI could use these improved formats as well.