HOUME-Insight-Agent

HOUME Insight Agent는 GitHub Issue/PR에 대해 Notion/Discord 팀 지식을 근거로 단일 계획/리뷰 코멘트를 남기는 자동화 에이전트입니다.

저장소 역할

• 구현 소스: 에이전트 런타임 코드, 스크립트, 테스트, CI 품질 체크
• 검증 표면: 리뷰/인덱싱 경로의 수동 검증 실행
• 런타임 정책: 이 저장소에서 자동 프로덕션 런타임은 운영하지 않음

운영 모드 (현재)

• 이 저장소에서는 구현 및 품질 체크를 유지합니다.
• 런타임 검증 워크플로는 수동 트리거로 운영합니다.
• 프로덕션 시크릿과 write-enabled 런타임 실행은 중앙 런타임 환경에서 관리합니다.

기술 스택

Agent Runtime

구분	스택
Runtime
Programming Language
Agent Framework
LLM Provider
RAG Index Store
Integrations

Tooling / Infra

구분	스택
Cloud
Auth
Observability
Package Manager
Version Control
Local Validation

아키텍처

Runtime

flowchart LR
  GH["GitHub Issue/PR Events"] --> Review["Review Workflow (GitHub Actions)"]
  Cron["Scheduled / Manual Trigger"] --> Index["Indexing Workflow (GitHub Actions)"]
  NextCycle["Next Indexing Cycle"]

  Index --> Notion["Notion API"]
  Index --> Discord["Discord API"]
  Index --> OpenAI["OpenAI API (Embeddings)"]
  Index --> S3["S3 (Index Artifacts)"]

  Review --> S3
  Review --> OpenAI2["OpenAI API (Generation)"]
  Review --> GHAPI["GitHub API (Comment Upsert)"]
  Review -. allowlist write only .-> NotionLog["Notion (Allowlisted Pages)"]
  Review -. allowlist write only .-> DiscordLog["Discord (Allowlisted Threads)"]
  NotionLog -. feedback for next run .-> NextCycle
  DiscordLog -. feedback for next run .-> NextCycle
  NextCycle -. target runtime repository only: schedule / workflow_dispatch .-> Index

Loading

Deployment / Operations

flowchart TB
  Dev["Developer"] --> GitHub["GitHub Repository"]
  GitHub --> CI["GitHub Actions"]

  CI --> OIDC["OIDC Assume Role"]
  OIDC --> IAM["AWS IAM Role"]
  IAM --> S3Store["S3 Bucket (index / manifest / checkpoint)"]

  CI --> OpenAIService["OpenAI API"]
  CI --> NotionService["Notion API"]
  CI --> DiscordService["Discord API"]
  CI --> Sentry["Sentry"]
  CI --> LangSmith["LangSmith"]

  CI --> Metrics["Ops Metrics<br/>(queue_wait_p95 / worker_latency_p95 / retry_count / dlq_count / index_load_p95 / retrieve_p95 / peak_rss_mb / workflow_total_seconds / trigger_drift_count)"]
  Metrics --> Gate{"Scale Threshold Breach?<br/>(2+ metrics / 1-2 weeks)"}
  Gate -- "No" --> Metrics
  Gate -- "Yes" --> Plan["Vector DB Migration Planning"]
  Plan --> DualRead["Dual-Read Validation<br/>(S3 path + Vector DB path)"]
  DualRead --> Cutover{"Cutover Decision"}
  Cutover -- "Pass" --> VectorDB["Vector DB (Future)"]
  Cutover -- "Fail" --> Rollback["Rollback to S3 path"]
  Rollback --> Metrics

Loading

로컬 검증 명령

pnpm install
pnpm run check

선택적 수동 런타임 검증:

pnpm run review
pnpm run review:pr
pnpm run index
pnpm run release-gate

이 저장소의 워크플로 범위

• .github/workflows/pr-quality-check.yml: 필수 PR 품질 게이트
• .github/workflows/secrets-validator.yml: 수동 검증 경로
• .github/workflows/issue-comment-upsert.yml: 수동 런타임 검증 경로
• .github/workflows/notion-indexing.yml: 수동 런타임 검증 경로

AWS security artifacts

• ops/aws/iam/oidc-trust-policy.json: GitHub OIDC trust policy template
• ops/aws/iam/policy-ci-runtime.json: CI runtime least-privilege template
• ops/aws/iam/policy-ingress.json: ingress least-privilege template
• ops/aws/iam/policy-worker.json: worker least-privilege template
• ops/aws/iam/policy-storage-indexing.json: storage/indexing least-privilege template
• ops/aws/security-runbook.md: secret rotation and access audit runbook
• .github/workflows/release-deployment-gate.yml: 릴리즈 게이트 판정/override 감사/배포 진입 제어 경로