document-haness/docs/PROVIDERS.md

Provider integration

공통 계약

모든 provider는 다음 인터페이스를 구현한다.

Provider.generate(ProviderRequest) -> ProviderResponse
Provider.check() -> dict

ProviderRequest는 stage, prompt, workdir, metadata를 가진다. ProviderResponse는 모델의 텍스트, provider/model 이름, 실제 command 또는 실행 메타데이터를 반환한다.

Provider는 초안의 의미를 해석하지 않는다. 호출·timeout·출력 수집만 담당하며 JSON/Markdown 계약 검증은 pipeline에서 수행한다.

Codex

기본 command 개념:

codex exec
  --sandbox read-only
  --skip-git-repo-check
  [--model MODEL]
  --output-last-message TEMP_FILE
  -

프롬프트는 stdin으로 전달한다. -는 비대화형 입력을 의미하고, 마지막 메시지는 임시 파일에서 읽는다. 문서 생성은 로컬 파일 변경이 필요 없으므로 기본 sandbox를 read-only로 둔다.

설정 예:

{
  "provider": "codex",
  "model": "",
  "timeout_seconds": 300,
  "options": {
    "binary": "codex",
    "sandbox": "read-only",
    "skip_git_repo_check": true,
    "extra_args": []
  }
}

환경 변수 CLARIDOC_CODEX_BIN으로 실행 파일을 지정할 수도 있다.

조직 래퍼:

{
  "provider": "codex",
  "options": {
    "command": ["/trusted/path/company-codex-wrapper", "--batch"]
  }
}

custom command는 stdout을 최종 응답으로 사용한다.

Claude Code

기본 command 개념:

claude -p --output-format text [--model MODEL] "Read the piped task..."

긴 프롬프트는 운영체제 argument 길이 제한을 피하기 위해 stdin으로 전달한다. 마지막 고정 query는 piped task의 출력 계약만 수행하도록 지시한다.

설정 예:

{
  "provider": "claude",
  "model": "",
  "timeout_seconds": 600,
  "options": {
    "binary": "claude",
    "extra_args": []
  }
}

환경 변수 CLARIDOC_CLAUDE_BIN 또는 신뢰된 options.command를 사용할 수 있다.

Google Antigravity

Antigravity는 Python SDK를 사용한다.

from google.antigravity import Agent, LocalAgentConfig

config = LocalAgentConfig(**options["config"])
async with Agent(config) as agent:
    response = await agent.chat(prompt)
    text = await response.text()

설치:

python -m pip install -e '.[antigravity]'

설정 예:

{
  "provider": "antigravity",
  "model": "",
  "timeout_seconds": 300,
  "options": {
    "config": {}
  }
}

model이 지정되고 options.config에 model이 없으면 하네스가 config 인수로 전달한다. SDK 버전에 따라 지원 인수가 다를 수 있으므로 잘못된 config는 명시적 오류로 종료한다.

SDK가 로컬 환경을 기준으로 동작하므로 provider는 실행 중 임시로 run directory를 current working directory로 사용한다. 프로세스 전체 cwd가 공유 상태이므로 lock으로 직렬화한다.

Mock

Mock은 외부 모델이 아니다. 다음을 위한 결정적 fixture다.

• planner JSON 계약 검증
• writer Markdown 배선 검증
• review JSON 파싱 검증
• revision loop 및 산출물 테스트
• CI에서 네트워크·인증 없이 회귀 테스트

Mock 점수는 실제 품질 판단으로 사용하면 안 된다.

doctor

claridoc doctor --config config/pipeline.multi-agent.example.json --json

• Codex/Claude: 실행 파일 경로 존재 확인
• Antigravity: Python module import 가능 여부 확인
• Mock: 항상 available

doctor는 로그인·권한·quota·실제 모델 응답까지 확인하지 않는다. 그것은 live invocation에서만 확인된다.

Provider 추가

1. src/claridoc/providers/에 Provider 구현을 추가한다.
2. stdout/SDK 응답을 문자열로 반환하고 timeout과 오류를 ProviderError 계열로 변환한다.
3. registry.py에 이름을 등록한다.
4. command/SDK를 가짜 구현으로 대체한 단위 테스트를 작성한다.
5. 인증 비밀은 config나 event log에 넣지 않는다.
6. 모델 출력 계약은 provider가 아니라 prompts.py와 pipeline parser에서 유지한다.