Repository Discovery Agent

An AI Agent that can answer questions about GitHub repositories for a user or an organization.

Run

1. Copy the example environment file and fill in the necessary values.

   cp .env.example .env 
   source .env

2. Run the app then visit localhost:5050.

   uv run -m discovery
   

Test

1. Run fast tests

   uv run -m unittest

2. Run slow tests

   source .env
   RUN_SLOW_TESTS=true uv run -m unittest

Authentication

GitHub Token

The application authenticates users with a GitHub auth token, by default. A user enters their GitHub token into the login screen, and all calls to GitHub are made with the user's token.

GitHub OAuth

The application can optionally use GitHub OAuth to authenticate users. To do so, create a GitHub OAuth app, then set the following environment variables:

export GITHUB_OAUTH_ENABLED=true
export GITHUB_CLIENT_ID=your_client_id
export GITHUB_CLIENT_SECRET=your_client_secret

To restrict users to one or more domains, or one or more email addresses, set one of the following environment variables.

export ALLOWED_DOMAINS=somedomain.example.com,anotherdomain.example.com
export ALLOWED_ADDRESSES=someone@example.com,another@example.com

Users are allowed to access the application if one of their verified email addresses on GitHub matches.

Build container

1. Build container

   uv pip compile pyproject.toml -o requirements.txt
   docker build -t repository-discovery .

2. Run with docker

   docker run -p 5050:5050 --env-file .env.docker repository-discovery

Exercise

Create a tool

Use the GitHub API documentation and add a new tool.

1. In the GithubClient, define a method that calls the GitHub API endpoint you've chosen.
2. Add a function to github_tools that calls your new method in the GitHub client. Return a JSON string of the data returned by the method.
3. Add a Python docstring to your function that describes how OpenAI should use the function.
4. Add the @tool() decorator to the function.
5. Register the new tool by adding it to the list of tools that are returned by the github_tools method.

Run the application and see if you can have OpenAI use your tool to fetch data.

Add a test for the new tool

Now make sure the agent integrates properly with OpenAI to use your tool. This test will use the LLM and take more time to run. The focus of the test should be to check that the agent uses the correct tool to answer the question, but we have limited ability to check that the response is correct.

1. Define a test_ method in test_repository_agent.py that will cover the new tool that was added.
2. Decorate the test method with the @slow decorator.
3. Add the @responses.activate decorator to the method to enable stubbing the API call.
4. Stub the API that your tool uses.
5. Send a question to the agent and assert the correct tools are called
6. Next assert the response by spot checking for relevant word(s).