Draft: prototype v1 api

[bsima]

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:

1. I started doing a RESTful-style design with e.g. /accounts endpoints, but the hledger CLI is organized around bal and reg, so now I'm thinking its best to mimic the CLI as closely as possible. Does that sound right?
2. 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.
3. 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?

[simonmichael]

Very interesting!

1. 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.)
2. 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 ?
3. hledger-web's test suite might be one way ? You can add http requests there IIRC.

[bsima]

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.

[bsima]

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.

[simonmichael]

Yes indeed.