Potpie

Potpie는 전체 코드베이스를 **지식 그래프 (knowledge graph)**로 변환합니다. 이는 모든 파일, 클래스, 함수의 구조적 인덱스로, 모든 관계와 각 코드 부분이 다른 모든 부분의 맥락 속에서 무엇을 하는지를 포착합니다. 이 그래프를 기반으로 구축된 AI 에이전트는 디버깅 (debugging)부터 기능 개발 (feature development)에 이르기까지, 코드를 직접 작성한 사람과 같은 정밀도로 코드를 추론할 수 있습니다.

빠른 시작 (Quick Start)

필수 요구 사항 (Prerequisites)

• Docker 설치 및 실행 중
• Git 설치됨
• uv가 포함된 Python 3.11+

설치 (Installation)

1. 저장소 복제 (Clone the repository)

   git clone --recurse-submodules https://github.com/potpie-ai/potpie.git
   cd potpie

2. 환경 설정 (Configure your environment)

   복사

   cp .env.template .env
   

   1

   2

   다음 필수 값들을 사용하여 .env 파일을 편집하세요:

   복사

   # App & Environment
   isDevelopmentMode=enabled
   ENV=development
   

   1

   2

   3

   4

...

   > **`CHAT_MODEL`**과 **`INFERENCE_MODEL`**은 각각 에이전트의 추론 (Reasoning) 및 지식 그래프 (Knowledge Graph) 생성에 사용됩니다. 모델 이름은 [LiteLLM](https://docs.litellm.ai/docs/providers)에서 요구하는 `provider/model_name` 형식을 따릅니다.

   > **💡 Ollama를 사용하시나요?** `LLM_PROVIDER=ollama`로 설정하고, `CHAT_MODEL=ollama_chat/qwen2.5-coder:7b` 및 `INFERENCE_MODEL=ollama_chat/qwen2.5-coder:7b`를 사용하세요.

   선택적 설정 (로깅 (Logging), 기능 플래그 (Feature flags), 객체 스토리지 (Object storage), 이메일 (Email), 분석 (Analytics) 등)의 전체 목록은 `.env.template`을 참조하세요.

3. **의존성 설치 (Install dependencies)**

   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync

4. 모든 서비스 시작 (Start all services)

   복사

   chmod +x scripts/start.sh
   ./scripts/start.sh
   

   1

   2

   3

   이 명령은 Docker 서비스를 시작하고, 마이그레이션 (Migrations)을 적용하며, FastAPI 앱과 Celery 워커 (Worker)를 시작합니다.

5. 상태 확인 (Health Check)

   복사

   curl -X GET 'http://localhost:8001/health'
   

   1

   2

6. 파싱 상태 확인 (Check parsing status)

   복사

   curl -X GET 'http://localhost:8001/api/v1/parsing-status/your-project-id'
   

   1

   2

모든 서비스를 중지하려면:

./scripts/stop.sh

이제 Potpie 프론트엔드 (Frontend)를 설정하세요

cd potpie-ui

cp .env.template .env
...

작동 원리 (How it works?)

Potpie는 사용자의 저장소를 Neo4j에 저장되는 **지식 그래프 (Knowledge Graph)**로 파싱합니다. 이를 통해 모든 파일, 함수, 클래스 및 이들 사이의 관계를 포착합니다. 에이전트는 실제 코드에 근거하여 질문에 답하고 작업을 완료하기 위해 이 그래프를 직접 읽습니다.

아키텍처 (Architecture)

• FastAPI가 API 계층 역할을 수행합니다. 모든 요청은 CORS, Logfire 트레이싱(tracing), 그리고 선택적인 Sentry 에러 트래킹(error tracking)과 함께 localhost:8001을 통해 들어옵니다.
• Firebase Auth가 프로덕션(production) 인증을 처리합니다. 개발 모드에서는 로컬에 더미 사용자가 생성되므로 Firebase가 필요하지 않습니다.
• Redis를 브로커(broker)로 사용하는 Celery Worker가 비동기 리포지토리(repo) 파싱을 처리합니다. 클로닝(cloning), AST 추출, 그리고 지식 그래프(knowledge graph) 구축은 완전히 백그라운드에서 실행됩니다.
• Conversation Service는 다회차 상호작용(multi-turn interactions) 전반에 걸쳐 채팅 세션과 에이전트 메모리(agent memory)를 관리합니다.
• Agent Router는 의도(intent)에 따라 프롬프트(prompt)를 올바른 사전 구축된 에이전트 또는 커스텀 에이전트로 전달합니다.
• Tool Service는 에이전트에게 호출 가능한 함수들을 노출합니다. 코드 검색, 파일 가져오기, 지식 그래프 쿼리, 웹 도구 등이 포함됩니다.
• Neo4j Knowledge Graph는 코드베이스를 속성 그래프(property graph)로 저장합니다. 함수, 클래스, 파일, 임포트(import), 호출 관계 등이 포함되며, 이는 모든 에이전트 컨텍스트(context)의 중추 역할을 합니다.
• PostgreSQL은 사용자, 프로젝트, 대화 및 메시지 기록을 저장합니다.

GitHub 인증 (GitHub Authentication)

셀프 호스팅 Git 제공자 (Self-Hosted Git Providers)

셀프 호스팅 Git 서버(예: GitBucket, GitLab 등)의 경우, 다음을 구성하십시오:

      uv sync

이렇게 하면 .venv 디렉토리가 생성되고 pyproject.toml의 모든 의존성(dependencies)이 설치됩니다.

GitHub 인증 설정 (GitHub Authentication Setup)

Potpie는 GitHub 리포지토리에 접근하기 위해 여러 인증 방법을 지원합니다:

GitHub.com 리포지토리의 경우:

옵션 1: GitHub App (프로덕션 환경 권장)

• 조직(Organization) 내에 GitHub App을 생성합니다.
• 환경 변수(Environment variables)를 설정합니다:
  복사

  GITHUB_APP_ID=your-app-id
  GITHUB_PRIVATE_KEY=your-private-key
  

  1

  2

  3

옵션 2: 개인 액세스 토큰 (Personal Access Token, PAT) 풀

• repo 스코프(Scope)를 가진 하나 이상의 GitHub PAT를 생성합니다.
• 환경 변수를 설정합니다 (여러 토큰의 경우 쉼표로 구분):
  복사

  GH_TOKEN_LIST=ghp_token1,ghp_token2,ghp_token3
  

  1

  2
• Potpie는 부하 분산(Load balancing)을 위해 풀에서 무작위로 토큰을 선택합니다.
• Rate Limit (속도 제한): 토큰당 시간당 5,000회 요청 (인증됨)

옵션 3: 인증되지 않은 접근 (공개 리포지토리 전용)

• 별도의 설정이 필요하지 않습니다.
• 공개 리포지토리(Public repositories)에 대한 폴백(Fallback)으로 자동 사용됩니다.
• Rate Limit (속도 제한): IP당 시간당 60회 요청 (매우 제한적임)

셀프 호스팅 Git 서버 (GitBucket, GitLab 등)의 경우:

  다음 환경 변수를 설정합니다:
  

  CODE_PROVIDER=github   # 옵션: github, gitbucket
  CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
  CODE_PROVIDER_TOKEN=your-token

중요: GH_TOKEN_LIST 토큰은 CODE_PROVIDER_BASE_URL 설정과 관계없이 항상 GitHub.com용으로 사용됩니다.

2. Potpie 시작하기

   모든 Potpie 서비스를 시작하려면 다음을 실행합니다:

   복사

   chmod +x scripts/start.sh
   ./scripts/start.sh
   

   1

   2

   3

   이 명령은 다음 작업을 수행합니다:

   • 필요한 Docker 서비스 시작
   • PostgreSQL이 준비될 때까지 대기
   • 데이터베이스 마이그레이션(Database migrations) 적용
   • FastAPI 애플리케이션 시작
   • Celery 워커(Worker) 시작

   선택 사항: Logfire 트레이싱(Tracing) 설정

   Pydantic Logfire를 사용하여 LLM 트레이스(Traces) 및 에이전트 동작을 모니터링하려면:

   1. https://logfire.pydantic.dev 에서 Logfire 토큰을 발급받습니다.
   2. .env 파일에 토큰을 추가합니다:
   복사

   LOGFIRE_TOKEN=your_token_here
   

   1

   2
   3. Potpie가 시작될 때 트레이싱이 자동으로 초기화됩니다. 트레이스는 https://logfire.pydantic.dev 에서 확인할 수 있습니다.

   참고: 트레이스를 Logfire 클라우드로 전송하지 않으려면 .env 파일에서 LOGFIRE_SEND_TO_CLOUD=false로 설정하십시오.

3. Potpie 중지

모든 Potpie 서비스를 중지하려면:

./scripts/stop.sh

Windows

./stop.ps1

이렇게 하면 다음 항목들이 안전하게(gracefully) 중지됩니다:

• FastAPI 애플리케이션
• Celery 워커 (worker)
• 모든 Docker Compose 서비스

Potpie의 사전 구축된 에이전트 (Prebuilt Agents)

Potpie는 소프트웨어 개발의 핵심 측면을 자동화하고 최적화하기 위한 일련의 전문 코드베이스 에이전트 (codebase agents)를 제공합니다:

커스텀 에이전트 (Custom Agents)

커스텀 에이전트 (Custom Agents)를 사용하면 반복적인 작업을 정밀하게 처리하는 개인화된 도구를 설계할 수 있습니다. 다음을 정의하세요:

• 시스템 지침 (System Instructions) - 에이전트의 작업, 목표 및 기대 출력
• 작업 (Tasks) - 작업 완료를 위한 개별 단계
• 도구 (Tools) - 지식 그래프 (Knowledge Graph) 쿼리 또는 코드 검색을 위한 함수

curl -X POST "http://localhost:8001/api/v1/custom-agents/agents/auto" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "An agent that takes stacktrace as input and gives root cause analysis and proposed solution as output"}'

더 자세한 내용은 문서 (documentation)에서 확인하세요.

유스케이스 (Use Cases)

수동 테스트에서 놓칠 수 있는 엣지 케이스 (Edge cases)를 다룹니다.</p>
</td>
<td valign="top">
<h3>기능 계획 (Feature Planning)</h3>
<p>요구사항이나 오픈 이슈 (Open issue)를 컴포넌트 분해, API 표면 (API surface), 제안된 코드 구조를 포함한 저수준 구현 계획 (Low-level implementation plan)으로 전환합니다.</p>
</td>

확장 및 통합 (Extensions & Integrations)