본 문서는 Go 언어를 활용하여 Google Cloud Platform (GCP), AI 모델 (Gemini, Vertex AI, Lyria, VOICEVOX), 그리고 각종 스토리지 및 네트워크 기능을 통합하는 「shouni」 에코시스템의 라이브러리 군과, 이를 응용한 Web/CLI 애플리케이션에 대해 논리적이고 계층적으로 정리한 것입니다.

🏗️ 코어 기반 라이브러리 군 (Core Infrastructure Libraries)

인프라스트럭처와의 접속, 통신의 안전성, 재시도(Retry) 제어, 그리고 스토리지 액세스를 추상화하는 기반 라이브러리입니다.

shouni/gcp-kit (GCP용 Web 툴킷)

GCP를 활용한 Web 애플리케이션이나 비동기 워커(Worker) 개발을 심플하고 견고하게 만들기 위한 Go 언어용 툴킷입니다. Cloud Run이나 Cloud Tasks 환경에서 보일러플레이트(Boilerplate)가 되기 쉬운 인증 및 세션 관리를 추상화합니다.

auth: Google OAuth2 인증 & 세션 관리-
이중 키 설계: 서명(HMAC)과 암호화(AES) 키를 분리하여 세션 데이터의 위변조 방지와 비닉화를 실현. AES 키 길이(16/24/32 bytes)를 기동 시 자동 검증. -
인가 필터링 (Authorization Filtering): 허가된 도메인이나 이메일 주소에 의한 화이트리스트 형식의 인가를 탑재. -
OIDC 검증: Cloud Tasks로부터의 워커 요청을 안전하게 수용하기 위한 OIDC 토큰 검증 미들웨어. -
견고한 CSRF 대책: subtle.ConstantTimeCompare를 통한 상수 시간 비교, 헤더 우선의 Body-Safe 검증, base64.RawURLEncoding을 채택.

tasks: 타입 안전한 (Type-safe) Cloud Tasks 엔큐 (Enqueue)- Generics ([T any])를 사용하여 독자적인 구조체를 타입 안전하게 직렬화(Serialize)하여 큐에 투입 가능. 서비스 계정(Service Account)을 이용한 OIDC 토큰 기반의 인증 설정을 단순화.

• Generics (-

worker: Cloud Tasks용 Worker 핸들러- Generics를 이용한 페이로드(Payload)의 자동 디코딩과, Cloud Tasks의 표준 사양에 기반한 에러 발생 시의 HTTP 상태 코드 관리(Retry-friendly)를 자동화.

shouni/netarmor (네트워크 보안 & 재시도 기반)

외부 통신에서의 「안정성」과 「안전성」을 강화하기 위한 네트워크 유틸리티 키트입니다.

securenet (강력한 방어): HTTP 클라이언트의 Transport 계층에서 접속 직전에 IP 주소를 검증하여, 프라이빗 IP 범위나 루프백(Loopback), 링크 로컬(Link-local), CGNAT 범위 등으로의 접속을 차단함으로써 SSRF나 DNS Rebinding 등의 TOCTOU 공격을 방지합니다. HTTP/HTTPS 외에도 gs:// 및 s3:// 스킴(Scheme) 검증에도 대응합니다. -
retry (견고한 재시도): backoff/v4를 기반으로, 일시적인 네트워크 에러에 대해 Context 취소나 최대 시도 횟수를 제어하면서 지수 백오프(Exponential Backoff)를 사용하여 자동 재시도를 수행합니다.

shouni/go-http-kit (HTTP 클라이언트 라이브러리)

netarmor/securenet과 연계하여 SSRF 대책 및 지수 백오프 재시도를 기본적으로 포함한, 표준 net/http와 호환되는 HTTP 클라이언트(httpkit.New)입니다.

재시도와 에러 핸들링: 5xx 에러 등의 타임아웃 시에는 지수 백오프로 재시도합니다. 4xx 에러는 NonRetryableHTTPError로 취급하여 재시도하지 않습니다. -
리소스 제한: MaxResponseBodySize (기본 25MB)에 의한 읽기 제한. -
요청 헬퍼 (Request Helper): JSON의 자동 인코딩/디코딩 (FetchAndDecodeJSON, PostJSONAndFetchBytes), Raw Body 전송 (PostRawBodyAndFetchBytes), 스트림 다운로드 (FetchStream, GetStream)를 지원. -
커스터마이징: WithMaxRetries

, WithInitialInterval, WithSkipNetworkValidation, WithHTTPClient` 등의 옵션으로 유연하게 설정 가능.

shouni/go-remote-io (유니버설 I/O 라이브러리)

Google Cloud Storage (GCS: gs://), Amazon S3 (s3://), 그리고 로컬 파일 시스템에 대한 액세스를 통일된 인터페이스로 자동 분기하는 I/O 라이브러리입니다.

• 풀 기능 리소스 조작: 읽기 (Open), 쓰기 (Write), 존재 확인 (Exists), 삭제 (Delete), 효율적인 콜백 방식의 목록 조회 (List)를 통합한 InputReader 및 OutputWriter를 제공. -
• Functional Options: Content-Type이나 Content-Disposition을 타입 안전(Type-safe)하게 지정하여 쓰기를 제어 가능. -
• 서명된 URL (Signed URL): GCS 및 S3 리소스에 대해 기한이 있는 서명된 URL (URLSigner)을 생성 가능. -
• 의존성: cloud.google.com/go/storage, aws-sdk-go-v2.

🤖 AI 프롬프트·생성 통합 라이브러리군 (AI Prompt & Generation Libraries)

LLM (Gemini 등)의 프롬프트 구축, 응답 관리, 그리고 이미지·음성 생성을 추상화하는 라이브러리군입니다.

shouni/go-prompt-kit (프롬프트·문서 배포 엔진)

AI를 위한 프롬프트 관리와 응답의 문서화 (Markdown에서 HTML로의 변환)를 지원하는 툴킷입니다.

• prompts (프롬프트 엔진): embed.FS로부터 파일을 자동 스캔하여 (Dynamic Resource Loader), text/template을 사용하여 구조체 데이터를 주입하고 동적으로 프롬프트를 생성. 모드 이름의 충돌 탐지 (Collision Detection) 탑재. -
• md (문서 배포 엔진): Markdown 응답을 스타일이 적용된 완전한 HTML 문서로 변환. CSS나 템플릿 교체가 가능한 모듈형 아키텍처 (Converter, Renderer, Runner) 채택.

shouni/go-gemini-client (Gemini API / Vertex AI 클라이언트)

shouni/netarmor의 재시도 (Retry) 기반을 채택한, Google Gemini API / Vertex AI용 듀얼 백엔드 대응 클라이언트입니다.

• 하이브리드 백엔드: API Key 방식 (Google AI Studio)과 Project ID/Location ID 방식 (Vertex AI)을 하나의 클라이언트에서 전환 가능. -
• 멀티모달 생성: 텍스트, 이미지, File API URI, 그리고 Vertex AI 환경에서의 gs:// 직접 참조 (genai.Part로의 포함)를 통한 입력을 지원. -
• File API 자동 관리: 업로드 후 Active 상태가 될 때까지의 자동 폴링 (Polling) 대기와 실패 시의 자동 클린업. -
• 이미지·음성 응답: ResponseMIMEType 지정에 따라 생성된 바이너리 데이터를 gemini.Response에 집약하여 추출. -
• Lyria 워크플로우: 가사 생성, 작곡 레시피 생성, Lyria 음성 생성을 통합. lyria 패키지에서 singleflight를 통한 중복 호출 억제와 섹션별 생성 및 WAV 결합을 지원.

shouni/gemini-image-kit (이미지 생성 코어)

Gemini API를 이용한 이미지 생성 워크플로우를 최적화하는 툴킷입니다.

• Unified Generator: 단일 참조 이미지 생성 (GenerateSingleImage)과 복수 참조 이미지의 통합 생성 (GenerateFusedImage)을 지원. -
• Hybrid Asset Workflow: Vertex AI 모드에서는 gs://

이미지를 직접 참조하며, Gemini API 모드에서는 File API의 캐시 일관성(Cache Consistency)과 라이프사이클(Lifecycle)을 자동으로 관리합니다. -
Intelligent MIME Prediction: 확장자에 기반하여 MIME Type을 자동 추측합니다. -
Fetch Policy Injection: 외부 URL로부터의 이미지 취득은 주입 가능한 ports.Downloader를 통해서만 제한하여, SSRF(Server-Side Request Forgery) 방지 및 도메인 제어를 애플리케이션 측에서 적용합니다. -
Selective Optimization: PNG/GIF 등을 인메모리(In-memory)에서 JPEG로 압축하고, MIME Type을 조정한 후 스트림 업로드(Stream Upload)합니다.

shouni/go-manga-kit (캐릭터 DNA 유지·작화 워크플로우)

Gemini Image Kit을 핵심(Core)으로 채택하여, 비구조화 문서(Unstructured Document)를 분석하고 AI를 통해 캐릭터 DNA의 일관성을 유지하며 만화를 생성하는 툴킷입니다.

3-Factor Consistency Control: 시드(Seed) 값(기반), 참조 에셋(외형), 언어 지시(상세)를 조합하여 캐릭터를 고정합니다. -
Concurrency Control: 세마포어(Semaphore)와 레이트 리미트(Rate Limit)를 통한 세밀한 병렬 실행 제어로, API 쿼터(API Quota, 429 에러)를 회피하는 견고한 배치 처리(Batch Processing)를 실현합니다. -
Smart Asset Management: gs:// 직접 참조 및 singleflight를 통한 중복 업로드 방지로 에셋 준비의 오버헤드(Overhead)를 줄입니다. -
5가지 워크플로우: DesignRunner(설정화 생성), ScriptRunner(대본 생성), PanelImageRunner(개별 패널 생성), PageImageRunner(재레이아웃·일괄 작화), PublishRunner(결과물 통합·HTML/Markdown 출력).

shouni/go-voicevox (VOICEVOX 음성 합성 툴킷)

VOICEVOX 엔진의 API를 사용하여 스크립트로부터 음성을 생성하는 툴킷입니다.

스크립트 분석: 태그([화자][스타일])가 붙은 행의 분석, 200자 상한에 따른 구두점 우선 문장(Segment) 분할, 그리고 스타일 ID의 캐시 해결(Cache Resolution). -
병렬 합성 제어 (internal/engine): errgroup.SetLimit, rate.Limiter, context.WithTimeout을 사용하여 세그먼트 단위로 /audio_query와 /synthesis를 안전하게 병렬 실행합니다. -
WAV 결합 및 출력: 여러 세그먼트의 WAV 파일 fmt/data 청크(Chunk)를 검증·결합·헤더 재계산하여, shouni/go-remote-io를 통해 로컬 또는 GCS로 출력합니다.

shouni/gemini-reviewer-core (AI 코드 리뷰 엔진 기반)

Git 리포지토리의 브랜치 간 차분(Diff)을 분석하고, Gemini API를 사용하여 AI 코드 리뷰를 자동 생성하는 코어 엔진입니다.

Git 조작 전략: 서버리스(Serverless) 환경을 위한 go-git (인메모리)과 로컬/CI를 위한 외부 명령 os/exec (강력한 클린업)를 유연하게 전환할 수 있습니다. -
참조 해결 및 클린업: 해시(Hash) 값의 직접 지정 대응 및 숫자만으로 된 브랜치 이름 해결 시 리모트 탐색(Remote Exploration) 우선 적용. 실행 시마다 git checkout -f / git clean -f -d를 통해 Detached HEAD 방지 및 상태 초기화. -
아키텍처 설계: 클린 아키텍처(Clean Architecture: Ports, Workflow, Runner, Adapter)를 철저히 준수하여 높은 테스트 용이성(Testability)과 확장성(Extensibility)을 제공합니다. -
결과물 공개: Markdown 리뷰 결과를 go-prompt-kit으로 HTML화하여 GCS나 S3에 투명하게(Transparently) 저장 및 공개합니다.

🚀 Web 애플리케이션·CLI 툴 (Web Applications & CLI Tools)

코어 기반 및 AI 라이브러리 군을 통합하여, Cloud Run / Cloud Tasks 또는 CLI 환경에서 동작하는 최종 결과물 애플리케이션입니다.

AP Manga Web (AI 만화 생성 Web 애플리케이션)

go-manga-kit

go-manga-kit를 활용하여 Cloud Run과 Cloud Tasks로 오케스트레이션(Orchestration)된 비동기 Web 애플리케이션입니다.

기능: Design(설정화 생성/Seed 추출), Script(대본 생성), Panel(개별 작화), Page(페이지 레이아웃 생성), Generate(일괄 생성)의 5가지 명령을 Web 폼에서 실행. -
아키텍처: 헥사고날 아키텍처(Hexagonal Architecture)와 서버리스 오케스트레이션(Serverless Orchestration)을 채택. OAuth 2.0 세션 인증 및 CSRF 검증이 포함된 Web 프론트엔드에서 Cloud Tasks로 엔큐(Enqueue)하면, OIDC 검증을 거친 워커(Worker)가 파이프라인(Pipeline)을 실행. -
결과 및 알림: GCS에 결과물(HTML/Images/JSON)을 저장하고, 서명된 URL(Signed URL)을 포함한 완료/에러 리포트를 Slack으로 알림.

Git Gemini CLI (AI 코드 리뷰 CLI)

gemini-reviewer-core를 이용하여 커맨드 라인(Command Line)에서 원격 리포지토리(Remote Repository)의 AI 코드 리뷰를 실행하는 도구입니다. Cobra 프레임워크를 채택했습니다.

리뷰 모드: -m 플래그를 통해 detail(상세한 코드 품질 및 유지보수성 리뷰)과 release(치명적인 버그나 취약점에 집중한 릴리스 판정)를 프롬프트 파일 전환 방식으로 지원. -
명령어:

• review: 차분(Diff)을 가져와 리뷰 결과를 표준 출력(Standard Output)에 표시. -

• publish: 리뷰 결과를 HTML로 변환하여 GCS에 저장하고, Slack으로 알림(SLACK_WEBHOOK_URL 설정 시).

주요 플래그: --repo-url, --base-branch, --feature-branch, --ssh-key-path, --gemini.

Git Gemini Web (AI 코드 리뷰 오케스트레이터)

gemini-reviewer-core를 Google Cloud 상에서 스케일링(Scaling)하기 위한 Web 프론트엔드 겸 오케스트레이터입니다.

비동기 실행 기반: Cloud Run과 Cloud Tasks를 결합하여, Web 폼 접수부터 무거운 분석 처리까지 비동기 큐잉(Queuing) 처리. 자동 재시도(Retry) 및 유량 제어(Traffic Control)를 통해 AI API의 레이트 리미트(Rate Limit)를 회피. -
하이브리드 AI 백엔드: 환경 변수에 따라 Google AI Studio(API Key)와 Vertex AI를 투명하게 전환 가능. -
인증 및 I/O: Google OAuth 2.0 / Gorilla Sessions를 통한 액세스 제어. go-remote-io를 통한 GCS로의 리뷰 결과(HTML) 저장 및 서명된 URL 발행. Slack 알림 대응.

AP Voice (AI 나레이션 음성 생성 CLI)

go-gemini-client와 go-voicevox를 통합하여, 긴 기술 문서 등을 분석하고 음성으로 변환하는 CLI 도구입니다.

AI-Driven Scripting: Web URL 또는 GCS (gs://) 문서를 분석하여, 최적의 화자 스타일(solo, dialogue, duet)을 지정한 나레이션 스크립트(텍스트)를 자동 생성. -
High-Speed Parallel Synthesis: Go의 병렬 처리(Parallel Processing)를 통해 VOICEVOX 엔진과 연동하여, 생성된 대본을 고속으로 WAV 파일화하고 결합. -
Unified Audio Pipeline: 입력(Web/GCS), 스크립트 생성, WAV 결합, 출력(Local/GCS)까지 일관되게 실행. Slack 알림 및 서명된 URL 발행 대응. -
명령어: ap-voice generate -i <URL/GCS> -m <mode> -o <출력처>

AP Chain (LLM 멀티스텝 구조화 문서 생성 CLI)

대량의 웹 페이지에서 정보를 병렬로 취득하고, LLM의 MapReduce 처리를 통해 논리적인 구조화 문서(Markdown/HTML)를 생성하는 CLI 도구입니다.

• MapReduce형 처리 (MapReduce-type processing): 세그멘테이션된 텍스트로부터 중간 요약본을 병렬로 생성(Map)하고, 이를 통합하여 중복 제거 및 섹션 재구성(Reduce)을 실시. 방대한 정보라도 상세 내용을 놓치지 않음. -
  추적 가능성 (Traceability): 생성된 각 섹션 직후에 정보원이 된 참조 URL 리스트를 자동으로 부여. -
  입출력 및 공유: 입력 파일(URL 리스트) 및 출력 대상으로 로컬 경로와 GCS(gs://)를 지원. 처리 결과의 Slack 알림과 서명된 URL(Signed URL)을 통한 보안 공유 기능을 구현.

AP Music (AI 음악 생성 오케스트레이터)

Lyria 3 Pro API를 이용한 음악 생성 파이프라인을 Cloud Run과 Cloud Tasks로 웹 애플리케이션화한 프로젝트입니다.

• 3-Factor Music Consistency: 시드 결정론 (Seed Determinism, 난수 시드 관리), 스타일 프롬프팅 (Stylistic Prompting, 언어적 스타일 정의), 보컬 아티큘레이션 (Vocal Articulation, 보컬 열량 강제 주입)을 통해 곡의 질감과 구성을 엄격하게 제어. -
  Smart Request & Stream Management: singleflight를 통한 중복 요청 집약과, 분할 생성된 WAV 섹션을 디코딩 없이 바이너리 레벨에서 직접 결합(Lossless Binary Merging)함으로써 열화 없는 장곡을 생성. -
  워크플로우 (Workflow): 텍스트/URL/이미지로부터 작사·작곡 (MusicRecipe JSON)·음성 생성·GCS 저장 (Signed URL 발행)을 일관되게 수행하는 흐름과, 이미 입력된 MusicRecipe로부터 음성 생성만 수행하는 흐름을 제공 (compose / generate_from_recipe). -
  History & Playback: OAuth/CSRF로 보호된 UI를 통해 GCS 상의 생성 이력 목록, 상세 보기, Signed URL을 통한 음성 프리뷰 및 이력 삭제 조작이 가능. Slack 알림 기능 탑재.

Discussion