PeterCat Documentation

PeterCat is an intelligent Q&A bot solution designed specifically for community maintainers and developers. It provides a conversational Agent configuration system, self-hosted deployment options, and an integrated application SDK.

Key capabilities include:

• Automated Bot Creation: Create a bot by simply providing a GitHub repository URL or name.
• Automatic Knowledge Ingestion: Automatically ingests GitHub documentation and issues to serve as the bot's knowledge base.
• Multi-platform Integration: Integrate via a conversational SDK for websites or install as a GitHub App.
• Advanced Agent Workflows: Beyond simple Q&A, it can perform project information queries, reply to Discussions, summarize PRs, conduct code reviews, and manage GitHub Issues (search, create, and reply).

PeterCat can be self-hosted using an AWS + Supabase stack. Detailed guides are available for different deployment scenarios:

• Local Development: For running the service on your local machine.
• AWS Deployment: For production-grade deployment on AWS.

Refer to the specific guides in the docs/guides/ directory for step-by-step instructions.

Before attempting a one-click deployment of Petercat on AWS, ensure you have the following ready:

1. An active AWS account.
2. Docker installed locally on your machine.

Petercat uses a .toml configuration file to manage deployment parameters for specific regions and stacks.

1. Copy the example config:

   cp .aws/petercat-example.toml .aws/petercat-[REGION_NAME].toml

2. Modify the file: Open the new file (e.g., .aws/petercat-ap-southeast.toml) and update the region and stack_name keys.

Example configuration for the Singapore region:

version = 0.1
[default.deploy.parameters]
stack_name = "petercat-selfhosted"
resolve_s3 = true
s3_prefix = "petercat-selfhosted"
region = "ap-southeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true

Once the database is initialized, you can start the services:

1. Start the Server: Run yarn run server:local. Verify it is running by visiting http://127.0.0.1:8001/api/health_checker.
2. Start the Client: Run yarn run client. Access the client at http://127.0.0.1:3000.

After setting up Supabase and the environment files, you must apply the database migrations.

1. Navigate to the migrations folder.
2. Install the Supabase CLI (e.g., via brew install supabase/tap/supabase).
3. Run supabase db push using the Postgres DB URL found in your server/.env file.

The URL format is: postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@127.0.0.1:5432/postgres.

cd migrations
supabase db push --db-url "postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@127.0.0.1:5432/postgres"

Because the Assistant component relies on browser APIs, you must disable Server-Side Rendering (SSR) using next/dynamic to prevent errors during the build or hydration process.

import dynamic from 'next/dynamic';
import '@petercatai/assistant/style';

const Assistant = dynamic(() => import('@petercatai/assistant').then(mod => mod.Assistant), { ssr: false });

// PeterCat AI Assistant: https://petercat.ai/
export const PeterCat = () => {
  return <Assistant token="your token" apiDomain="https://api.petercat.ai" />;
};

Petercat requires specific environment configuration for both the client and the server.

1. Client Configuration: Copy client/.env.local.example to client/.env.
2. Server Configuration: Copy server/.env.local.example to server/.env.
3. Supabase Integration: You must synchronize the SERVICE_ROLE_KEY between your Supabase installation and the Petercat server. Locate the SERVICE_ROLE_KEY in your Supabase docker/.env file and paste it into the SERVICE_ROLE_KEY field in server/.env.

cp client/.env.local.example client/.env
cp server/.env.local.example server/.env

To get TypeScript type support for your database fields, use the Supabase CLI to generate types from your local migrations:

cd migrations
supabase start
supabase gen types typescript --local > database.types.ts

PeterCat uses yarn as its package manager. Use the following commands to set up the repository and run different components in debug mode:

Setup

# Clone the repository
git clone https://github.com/petercat-ai/petercat.git

# Install dependencies
yarn run bootstrap

Debugging Commands

• Client: yarn run client
• Assistant: yarn run assistant
• Server: yarn run server
• Full Stack (Client + Server): yarn run client:server
• Assistant Server: yarn run assistant:server

Building and Publishing

• Assistant Build:

  cd assistant
  yarn run build
  npm publish

• Docker Build: yarn run build:docker
• PyPI Build/Publish: yarn run build:pypi and yarn run publish:pypi