# Provider integration

## 공통 계약

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

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

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

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

## Codex

기본 command 개념:

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

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

설정 예:

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

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

조직 래퍼:

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

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

## Claude Code

기본 command 개념:

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

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

설정 예:

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

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

## Google Antigravity

Antigravity는 Python SDK를 사용한다.

```python
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()
```

설치:

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

설정 예:

```json
{
  "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`

```bash
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에서 유지한다.