chore(example): created runnable example

[InfraK]

create new example folder with a basic example project, pulling in the required dependencies, updated readme files to point to this new folder

[jemc]

If these runnable examples are meant to replace the ones that were in the documentation, I'd prefer to have each example be its own file. As it stands, I think this PR improves testability of the code examples, but degrades the discoverability and readability of the code examples. I'd like to find a way to solve for both.

Additionally, as it stands currently, if I want to just run an example, I end up running all of the examples, and I also need to have credentials for every possible adapter that Kurt has.

I can see why you wanted to keep things DRY and avoid the expansion of generation examples multiplied by the number of adapter examples. However, I'd like to propose a different approach to solving that problem. Rather than having the top-level file be a consolidated place where all examples are run, I think it would be best to do have each example separate, but use a consolidated function for Kurt setup. Here's my concrete proposal:

• Each generation example is in its own separately runnable file.
• Each generation example uses a createKurt function (defined in a separate ./createKurt.ts file) to return a Kurt instance
• The createKurt function looks at environment variables to determine which adapter and which model to use, and it has some basic validation on those env vars (verifying that they are present and have an appropriate value). Here's a basic proposal of env vars:
  • KURT_ADAPTER (allowed values: open-ai, vertex-ai)
  • KURT_MODEL (value validated by the isSupportedModel static function of the selected adapter)
  • (whatever other env vars are required for the particular adapter should also be validated that they are present, and show an explicit error if they were omitted)

This approach has a few benefits to mention:

• Each example is separately runnable, so somebody can easily pick an example to tweak and try new things with it
• Somebody only needs the credentials for one valid LLM provider adapter.
• The expressed purpose of Kurt is to make it easy to build an application that works with any LLM, so it makes sense from an "eating our own dogfood" perspective to make it so that our examples act like this (an example application that works with any selected LLM)
• The createKurt function will not just be for our own testing convenience, but also be a great example in its own right.
  • In fact, I can imagine people directly copy-pasting it into their application setup code and removing any adapters they don't care about supporting in their application.
  • I almost want to make this function available as a library function they could pull in as needed, but not sure how to do that without making it depend on every single adapter library separately (which would be a bad deal for all those unnecessary transitive dependencies on any adapters that the downstream apps didn't want to use)

What do you think?

[InfraK]

I mostly agree with everything, I'll take another pass at the comment tomorrow, but I think that we might want to use hard-coded values with multiple entry-points, one for each adapter, this at least gives more visibility into how the examples work, and we leave env variables strictly for credentials management, since the env files are not committed

I may just give you a brief call tomorrow so that we can align on an approach.

[InfraK]

So, after putting some more thought into it, given that these are meant to be examples, keeping it DRY doesn't make much sense, the priority should be in simplicity.

I'm thinking at this moment to create the following examples:

• One for each specific Adapter, keeping it as simple as possible (like the ones on the Readme before)
• One that creates the model/adapter agnostic, and is a little bit more complicated, but still a single file.

The environment variables will be used across all the examples for credentials, each example should be able to run on its own, as well as documenting how to run them in the readme.

How does this sound?

[jemc]

@InfraK - That sounds good.

I think the one thing I'd suggest is to ensure that in the model-agnostic example, we should show all three generation methods (similar to the 3 examples in the current Kurt README).

In a followup PR I will make a script that runs as a prepackage hook to copy snippets from each example file into the markdown READMEs prior to NPM publish.

[InfraK]

@jemc In order to keep the pull requests small, I'll split the examples here and leave the model-agnostic one for a follow up, does that sound good?

[jemc]

Sounds good!

[github-actions[bot]]

:tada: This PR is included in version @formula-monks/kurt-v1.3.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[github-actions[bot]]

:tada: This PR is included in version @formula-monks/kurt-open-ai-v1.5.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[github-actions[bot]]

:tada: This PR is included in version @formula-monks/kurt-vertex-ai-v1.4.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: