goose/CONTRIBUTING.md

Contributing

We welcome Pull Requests for general contributions. If you have a larger new feature or any questions on how to develop a fix, we recommend you open an issue before starting.

Prerequisites

Goose uses uv for dependency management, and formats with ruff. Clone goose and make sure you have installed uv to get started. When you use uv below in your local goose directly, it will automatically setup the virtualenv and install dependencies.

We provide a shortcut to standard commands using just in our justfile.

Development

Now that you have a local environment, you can make edits and run our tests!

Run Goose

If you've made edits and want to try them out, use

uv run goose session start

or other goose commands.

If you want to run your local changes but in another directory, you can use the path in the virtualenv created by uv:

alias goosedev=`uv run which goose`

You can then run goosedev from another dir and it will use your current changes.

Run Tests

To run the test suite against your edges, use pytest:

uv run pytest tests -m "not integration"

or, as a shortcut,

just test

Enable traces in Goose with locally hosted Langfuse

Note

This integration is experimental and we don't currently have integration tests for it.

Developers can use locally hosted Langfuse tracing by applying the custom observe_wrapper decorator defined in packages/exchange/src/exchange/observers to functions for automatic integration with Langfuse, and potentially other observability providers in the future.

• Add an observers array to your profile containing langfuse.
• Run just langfuse-server to start your local Langfuse server. It requires Docker.
• Go to http://localhost:3000 and log in with the default email/password output by the shell script (values can also be found in the .env.langfuse.local file).
• Run Goose with the --tracing flag enabled i.e., goose session start --tracing
• View your traces at http://localhost:3000

To extend tracing to additional functions, import from exchange.observers import observe_wrapperand use theobserve_wrapper()decorator on functions you wish to enable tracing for.observe_wrapper` functions the same way as Langfuse's observe decorator.

Read more about Langfuse's decorator-based tracing here.

Other observability plugins

In case locally hosted Langfuse doesn't fit your needs, you can alternatively use other observer telemetry plugins to ingest data with the same interface as the Langfuse integration. To do so, extend packages/exchange/src/exchange/observers/base.py:Observer and include the new plugin's path as an entrypoint in exchange's pyproject.toml.

Exchange

The lower level generation behind goose is powered by the exchange package, also in this repo.

Thanks to uv workspaces, any changes you make to exchange will be reflected in using your local goose. To run tests for exchange, head to packages/exchange and run tests just like above

uv run pytest tests -m "not integration"

Evaluations

Given that so much of Goose involves interactions with LLMs, our unit tests only go so far to confirming things work as intended.

We're currently developing a suite of evaluations, to make it easier to make improvements to Goose more confidently.

In the meantime, we typically incubate any new additions that change the behavior of the Goose through opt-in plugins - Toolkits, Moderators, and Providers. We welcome contributions of plugins that add new capabilities to goose. We recommend sending in several examples of the new capabilities in action with your pull request.

Additions to the developer toolkit change the core performance, and so will need to be measured carefully.

Conventional Commits

This project follows the Conventional Commits specification for PR titles. Conventional Commits make it easier to understand the history of a project and facilitate automation around versioning and changelog generation.

Release

In order to release a new version of goose, you need to do the following:

1. Update CHANGELOG.md. To get the commit messages since last release, run: just release-notes
2. Update version in pyproject.toml for goose and package dependencies such as exchange
3. Create a PR and merge it into main branch
4. Tag the HEAD commit in main branch. To do this, switch to main branch and run: just tag-push
5. Publish a new release from the Github Release UI