Skip to content

Latest commit

 

History

History
190 lines (123 loc) · 10.6 KB

CONTRIBUTING.md

File metadata and controls

190 lines (123 loc) · 10.6 KB

Contributing

Thanks for your interest in contributing! Whether you’re here to build new capabilities or refine existing ones, you’re in the right place.

How you can contribute

  • Build new agent tools: Add integrations or capabilities agents can use.
  • Improve existing tools: Fix bugs, enhance features, or optimize performance and UX.
  • Backend or frontend enhancements: Extend APIs, domain models, UI, or developer workflows.
  • Docs and examples: Clarify guides, add samples, and improve onboarding.
  • Tests and quality: Increase coverage, add type hints, and refine automated checks.

Fast path to your first tool

Impactful contributions today come from adding new agent tools (integrations and capabilities agents can use). If you’re here to build one, follow these steps:

  1. Set up the environment following Development environment.
  2. Follow Implementing new tools to implement the new tool.
  3. Open a draft PR early to get quick feedback.

Communication and support

  • Questions or ideas? Open an issue in GitHub Issues or chat with us on Discord.
  • Prefer small, focused PRs with clear motivation and testing notes.

Before submitting changes, please run checks and tests as described in Automated tests, and keep code style consistent with existing conventions (see Conventions and best practices).

Development environment

Requirements

Setup

To install development environment dependencies run:

devbox install && devbox run install

The first devbox command installs devbox packages (Python, Node, etc.), and the second installs Poetry and PNPM dependencies, in addition to creating a .env file from sample.env. This process may take a while the first time you run it.

Review .env and at least set an OpenAI API key or Azure OpenAI endpoint and API key. Check the rest of the available settings in the .env file in case you want to enable additional features.

Start the Postgres database:

devbox run postgres

Start Keycloak instance used for authentication:

devbox run keycloak

Browser Tool

If you want to try the Tero Browser tool, you’ll also need to start the Playwright MCP server:

devbox run playwright

Run Tero

You can run the backend with hot reloads with this command:

devbox run backend

And the frontend with hot realoads with this one:

devbox run frontend

You can now access Tero at the URL provided by the frontend run command and log in with test user and test password.

Now you have a full environment with hot reloads that you can use to apply changes to Tero backend or frontend.

Browser Copilot

If you want to work with the Browser Copilot, you can run this command to start a browser with the extension installed and with hot reloads:

devbox run browser

Automated tests

To run automated backend tests run:

devbox run tests

Additionally, you should also run type checks for backend code when you modify it (this avoids many unexpected bugs when running the application):

devbox run check

Database migrations

When you need to alter the SQL schema or data you can generate new DB migrations with:

devbox run new-migration "<migration_name>"

This will generate a new migration based on changes in any of the domain classes extending SQLModel with table=True.

To run DB migrations against the local database:

devbox run migrations

devbox run postgres automatically updates the database with migrations when it is run.

User guide changes

To preview updates to the published user guide locally with hot reload, start a docs server:

devbox run docs

And open the URL printed in the terminal to view the docs.

Architecture

Here are the main components of the Tero solution:

architecture diagram

Some of the components are optional depending on Tero usage and configuration.

Project structure

Inside src folder you can find a folder for each of the main Tero components:

Folder Contents
backend The source code of the backend Python service
frontend The source code of the frontend. The frontend is packaged and delivered as part of the backend.
browser-extension The source code for the browser copilot extension
common Common source code used both by the frontend and browser copilot extension

Implementing new tools

Before implementing a new tool, check the available tools in the src/backend/tero/tools folder. It is also good practice to ask about plans for the tool by creating a GitHub issue, in case someone else has the same idea so we can collaborate.

To create a new tool:

  1. Create a new module inside the tools directory with the name of the tool (e.g., my-tool).
  2. Create a tool-schema.json that specifies the parameters the user can set to configure the tool. This is used by the frontend to display the configuration modal, and by the backend to validate configurations.
  3. Create a tool.py containing a class extending AgentTool.
  4. Set a stable id for your tool. This is used in the database to reference the tool configuration.
  5. If an agent could use multiple instances of the tool, each with its own configuration, add a -* suffix to the id. In the configure method, override it so each configuration has a unique id. See the MCP Tool for an example.
  6. Implement the necessary logic in AgentTool methods, especially build_langchain_tools, which should build LangChain tools used by the agent. Check AgentTool in core.py for other methods you can override to control the tool lifecycle.
  7. Add your tool to the ToolRepository, so it can be listed when retrieving available tools and then configured.
  8. Implement at least one test that verifies the proper behavior of your tool in test_tools.py.
  9. Run the entire test suite with devbox run tests and devbox run check to verify proper type resolution in Python and avoid potential bugs.
  10. Select a proper icon for your tool. Ideally one that is provided by Tabler Icons or at least aligns with the design.
  11. Add internationalization (i18n) strings for the configuration parameters, name of the tool, and description in AgentToolConfigEditor.vue. You can use a Tero agent to translate texts you’re unsure about; the Tero team will also help refine texts in your PR.
  12. Add a mapping from your tool id to the proper icon in useToolConfig.ts.
  13. Add a new file in docs/guide/tools for the new tool explaining what it does and how to configure it.
  14. Add proper include to the new file in docs/guide/tools/index.md.
  15. Test your tool and share your shiny new tool with the rest of the community by sending a pull request to this GitHub repository!

Optionally, create additional Python scripts, new migrations, and any additional resources you need for your new tool.

Conventions and best practices

In general we follow common programming good practices and some language specific practices. Here are some that we’d like to highlight:

  • Run automated checks and tests before submitting a PR. Don’t waste time waiting for the pipeline or for someone to point out an issue you could have detected earlier.
  • Always check existing code and follow the same conventions and coding style to keep it consistent (naming, order of methods and parameters, framework usage, module structure, etc.).
  • Use proper TypeScript types and Python type hints as much as possible to clarify method contracts and avoid bugs.
  • When adding new functionality, add appropriate automated tests.
  • Prefer “Clean Code” ordering (callers before callees), keep variables and declarations near where they are used, and follow the KISS (Keep It Simple Stupid) principle.
  • Use comments to explain the “why” (when necessary), not the “what”. Use function and variable names for the “what”. Avoid comments that simply restate what the code already expresses.