Skip to content

Commit 958d741

Browse files
rafaelscostarafaelscosta
authored
docs: draft Epic 184 Kimi provider plan
Adds draft Epic 184 and Story 184.1 for OpenAI-compatible Kimi provider support. This publishes the plan only and does not close #184.
1 parent 21337b6 commit 958d741

2 files changed

Lines changed: 267 additions & 0 deletions

File tree

‎docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Epic 184: Kimi K2.5 Provider Support
2+
3+
## Metadata
4+
5+
| Campo | Valor |
6+
|-------|-------|
7+
| Epic ID | 184 |
8+
| Status | Draft |
9+
| Source Issue | #184 |
10+
| Issue URL | https://github.com/SynkraAI/aiox-core/issues/184 |
11+
| Repository | SynkraAI/aiox-core |
12+
| Priority | P4 |
13+
| Area | Core runtime, AI providers, LLM routing |
14+
15+
## Objetivo
16+
17+
Adicionar suporte nativo e backward-compatible para Kimi K2.5 da Moonshot AI como provider OpenAI-compatible no `aiox-core`, permitindo uso via Moonshot API ou endpoints compatíveis sem quebrar os providers existentes `claude` e `gemini`.
18+
19+
## Code Reality
20+
21+
- `.aiox-core/infrastructure/integrations/ai-providers/ai-provider.js` define a interface base `AIProvider` para execução, retry, status e metadata.
22+
- `.aiox-core/infrastructure/integrations/ai-providers/ai-provider-factory.js` registra apenas `claude` e `gemini`, carrega `.aiox-ai-config.yaml`, mantém cache de providers e possui listas hardcoded em `getAvailableProviders()` e `getProvidersStatus()`.
23+
- `ClaudeProvider` e `GeminiProvider` são wrappers de CLI; Kimi K2.5 deve ser HTTP/OpenAI-compatible, não wrapper de CLI.
24+
- `docs/guides/llm-routing.md` já cobre roteamento Claude Code para DeepSeek via endpoint Anthropic-compatible, mas isso é diferente de provider nativo no factory de `AIProvider`.
25+
- Existe uma worktree antiga `feat/kimi-ide-integration-20260507`, porém seu escopo é Kimi como target de IDE sync (`.kimi/skills` e transformer), não o provider LLM solicitado no issue #184.
26+
- A documentação oficial da Kimi API declara compatibilidade com o formato OpenAI e usa `https://api.moonshot.ai/v1` como `base_url`; com esse `base_url`, o endpoint relativo de chat é `/chat/completions`.
27+
28+
## Escopo
29+
30+
- Criar um provider HTTP genérico `OpenAICompatibleProvider` reaproveitável para Kimi e outros endpoints compatíveis.
31+
- Registrar aliases `openai-compatible` e `kimi` no factory, com preset seguro para Moonshot/Kimi.
32+
- Permitir configuração por `.aiox-ai-config.yaml` e variáveis de ambiente, sem registrar segredos em logs ou docs.
33+
- Garantir que `claude` e `gemini` continuem sendo o default e o fallback atuais.
34+
- Documentar uso de Kimi K2.5 e OpenRouter/Moonshot como configuração, não como dependência obrigatória.
35+
36+
## Fora de Escopo
37+
38+
- Fazer chamadas reais para Moonshot, OpenRouter ou qualquer provider externo nos testes.
39+
- Migrar toda a estratégia de LLM routing do Claude Code.
40+
- Incorporar ou mergear a branch de Kimi IDE sync nesta story.
41+
- Prometer tool calling perfeito para todos os endpoints OpenAI-compatible sem testes de contrato por provider.
42+
- Armazenar API keys no repositório.
43+
44+
## Stories
45+
46+
| Story | Título | Status | Prioridade | Ordem |
47+
|-------|--------|--------|------------|-------|
48+
| 184.1 | OpenAI-Compatible Kimi Provider Contract | Draft | P4 | 1 |
49+
50+
## Ordem de Execução
51+
52+
### Sequencial
53+
54+
1. Validar `STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md` com PO/architect para confirmar que o escopo é provider LLM, não IDE sync.
55+
2. Implementar `OpenAICompatibleProvider` com testes unitários sem rede.
56+
3. Registrar aliases `openai-compatible` e `kimi` no provider factory e remover hardcodes de listas onde necessário.
57+
4. Atualizar docs e exemplos de `.aiox-ai-config.yaml`.
58+
5. Rodar validações focadas e publicar PR.
59+
60+
### Paralelizável
61+
62+
- Documentação de uso pode ser preparada em paralelo aos testes depois que o contrato de configuração estiver definido.
63+
- Expansão futura para a branch de Kimi IDE sync deve rodar em outro ciclo, depois do provider LLM estar validado.
64+
65+
## Validation Gates
66+
67+
- `npm test -- --runTestsByPath tests/infrastructure/ai-providers/ai-provider-factory.test.js`
68+
- Novo teste focado para `OpenAICompatibleProvider`, com `fetch` mockado e sem chamadas de rede.
69+
- `npm run lint`
70+
- `npm run typecheck`
71+
- `npm run validate:manifest`, se novos arquivos entrarem no pacote instalável.
72+
73+
## Referências
74+
75+
- Issue #184: https://github.com/SynkraAI/aiox-core/issues/184
76+
- Kimi API overview: https://platform.kimi.ai/docs/api/overview
77+
- Kimi chat completions endpoint: https://platform.kimi.ai/docs/api/chat
78+
- Kimi K2.5 quickstart: https://platform.moonshot.ai/docs/guide/kimi-k2-5-quickstart

‎docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Story 184.1: OpenAI-Compatible Kimi Provider Contract
2+
3+
## Metadata
4+
5+
| Campo | Valor |
6+
|-------|-------|
7+
| Story ID | 184.1 |
8+
| Epic | [184 - Kimi K2.5 Provider Support](./EPIC-184-KIMI-K2-5-PROVIDER.md) |
9+
| Status | Draft |
10+
| Executor | @dev |
11+
| Quality Gate | @architect |
12+
| quality_gate_tools | npm test focused, npm run lint, npm run typecheck, npm run validate:manifest |
13+
| Points | 8 |
14+
| Priority | P4 |
15+
| Story Order | 1 |
16+
| Source Issue | #184 |
17+
| Issue URL | https://github.com/SynkraAI/aiox-core/issues/184 |
18+
| Implementation Repository | SynkraAI/aiox-core |
19+
| Start Gate | PO/architect validation must confirm provider scope and no overlap with Kimi IDE sync work. |
20+
21+
## Status
22+
23+
- [x] Draft
24+
- [ ] PO validated
25+
- [ ] Ready for implementation
26+
- [ ] Ready for Review
27+
- [ ] Done
28+
29+
## Executor Assignment
30+
31+
```yaml
32+
executor: "@dev"
33+
quality_gate: "@architect"
34+
quality_gate_tools:
35+
- npm test focused
36+
- npm run lint
37+
- npm run typecheck
38+
- npm run validate:manifest
39+
accountable: "pedro-valerio"
40+
domain: "*"
41+
deploy_type: "none"
42+
```
43+
44+
## Community Origin
45+
46+
**Discussion URL**: https://github.com/SynkraAI/aiox-core/issues/184
47+
**Author**: GitHub issue author
48+
**Approved Date**: 2026-03-11
49+
**Approved By**: AIOX triage via `status: confirmed`
50+
51+
## Story
52+
53+
**As a** framework maintainer,
54+
**I want** Kimi K2.5 to be available through a generic OpenAI-compatible provider in the AIOX provider factory,
55+
**so that** agents can use Moonshot/OpenRouter-compatible model endpoints without replacing the existing Claude/Gemini provider contract.
56+
57+
## Contexto
58+
59+
Issue #184 asks for native Kimi K2.5 support as an alternative to OpenAI or Claude. The current implementation already has an `AIProvider` base class, `ClaudeProvider`, `GeminiProvider` and a factory that loads `.aiox-ai-config.yaml`, but the factory only knows `claude` and `gemini`.
60+
61+
Official Kimi documentation confirms the API is OpenAI-compatible and uses:
62+
63+
- `base_url`: `https://api.moonshot.ai/v1`
64+
- chat completions endpoint relative to that base URL: `/chat/completions`
65+
66+
The correct implementation path is a reusable `OpenAICompatibleProvider` plus a Kimi preset/alias. A Kimi-specific hardcoded provider would solve less and create avoidable duplication.
67+
68+
## Acceptance Criteria
69+
70+
- [ ] AC1: A new `OpenAICompatibleProvider` exists under `.aiox-core/infrastructure/integrations/ai-providers/` and extends the existing `AIProvider` contract.
71+
- [ ] AC2: The provider supports `baseURL`/`baseUrl`, `apiKey`, `apiKeyEnv`, `model`, `timeout`, optional default headers and Chat Completions-compatible request payloads.
72+
- [ ] AC3: The provider never logs raw API keys and returns the existing `AIResponse` shape with provider/model/duration metadata.
73+
- [ ] AC4: `ai-provider-factory.js` registers `openai-compatible` and `kimi` aliases without changing the default `claude` primary and `gemini` fallback.
74+
- [ ] AC5: Kimi default config uses Moonshot's OpenAI-compatible base URL and a Kimi K2.5 model identifier only as a configurable preset, not as a hard dependency.
75+
- [ ] AC6: `getAvailableProviders()` and `getProvidersStatus()` include configured providers without hardcoding only `claude` and `gemini`.
76+
- [ ] AC7: Tests mock HTTP/fetch and cover success, API error, missing key, timeout or network failure, JSON response parsing and factory alias registration.
77+
- [ ] AC8: Documentation shows `.aiox-ai-config.yaml` examples for Moonshot/Kimi and OpenRouter-style overrides without committing secrets.
78+
- [ ] AC9: Existing Claude/Gemini provider tests continue to pass unchanged in behavior.
79+
- [ ] AC10: The story does not merge or depend on the stale Kimi IDE sync worktree; IDE sync can become a separate future story if still desired.
80+
81+
## CodeRabbit Integration
82+
83+
### Story Type Analysis
84+
85+
**Primary Type**: Core runtime feature
86+
**Secondary Type(s)**: Provider abstraction, configuration, documentation
87+
**Complexity**: Medium-high
88+
89+
### Specialized Agent Assignment
90+
91+
**Primary Agents**:
92+
- @dev
93+
- @architect
94+
95+
**Supporting Agents**:
96+
- @qa
97+
- @po
98+
- @devops
99+
100+
### Quality Gate Tasks
101+
102+
- [ ] Pre-Commit (@dev): Run provider factory tests and the new OpenAI-compatible provider tests.
103+
- [ ] Pre-PR (@devops): Confirm no secrets are committed and manifest updates match package files.
104+
- [ ] Architecture Review (@architect): Confirm the design is generic OpenAI-compatible provider plus Kimi preset, not a one-off Kimi-only fork.
105+
106+
## Tasks / Subtasks
107+
108+
- [ ] T1: Confirm exact provider file paths and exports from current `ai-providers` module.
109+
- [ ] T2: Implement `OpenAICompatibleProvider` using native fetch or an existing local HTTP primitive, with graceful fallback for unsupported runtimes if needed.
110+
- [ ] T3: Add `kimi` and `openai-compatible` factory registration, config merging and provider status discovery.
111+
- [ ] T4: Add deterministic tests with mocked HTTP responses and no external network calls.
112+
- [ ] T5: Update docs with Kimi/Moonshot and OpenRouter configuration examples.
113+
- [ ] T6: Update manifest/entity registry only if required by existing packaging gates.
114+
- [ ] T7: Run focused tests, lint, typecheck and manifest validation.
115+
116+
## Dev Notes
117+
118+
- Do not add a live Moonshot/OpenRouter integration test in CI.
119+
- Do not introduce a new SDK dependency unless native fetch is insufficient and the dependency is justified in the PR.
120+
- Prefer `apiKeyEnv` defaults such as `MOONSHOT_API_KEY` for Kimi and allow explicit override.
121+
- Treat `baseURL` and `baseUrl` as equivalent input names for compatibility with common OpenAI-style config.
122+
- Preserve current default provider behavior: `primary: claude`, `fallback: gemini`.
123+
- The stale `aiox-core-kimi` branch/worktree is scoped to IDE sync and should not be replayed into this story without a separate decision.
124+
125+
## Testing
126+
127+
Required focused validation:
128+
129+
```bash
130+
npm test -- --runTestsByPath tests/infrastructure/ai-providers/ai-provider-factory.test.js
131+
npm test -- --runTestsByPath tests/infrastructure/ai-providers/openai-compatible-provider.test.js
132+
npm run lint
133+
npm run typecheck
134+
npm run validate:manifest
135+
```
136+
137+
If the provider test lands under a different path, update this section and the File List during implementation.
138+
139+
## Dependencies
140+
141+
- **Blocked by:** PO/architect validation of this draft.
142+
- **Blocks:** issue #184 closure.
143+
- **Related:** issue #137; existing LLM routing docs; Kimi IDE sync branch is adjacent but not in scope.
144+
145+
## Definition of Ready
146+
147+
- [ ] PO validation completed with no unresolved blocker.
148+
- [x] Target provider surfaces confirmed against current code reality.
149+
- [x] Acceptance criteria are testable without live API calls.
150+
151+
## Definition of Done
152+
153+
- [ ] All ACs complete.
154+
- [ ] Focused tests pass.
155+
- [ ] Lint and typecheck pass.
156+
- [ ] Manifest validation passes if package files are added.
157+
- [ ] File List and Dev Agent Record are updated.
158+
- [ ] Issue #184 has implementation evidence and can be closed or explicitly moved to follow-up scope.
159+
160+
## Dev Agent Record
161+
162+
### Debug Log
163+
164+
- Draft created from issue #184 and current repo inspection on 2026-05-08.
165+
- Confirmed no open PR currently targets Kimi/Moonshot/provider support.
166+
- Identified stale `aiox-core-kimi` branch/worktree as IDE sync scope, not provider LLM scope.
167+
- Confirmed current provider factory registers `claude` and `gemini` only.
168+
- Verified current Kimi API docs: OpenAI-compatible base URL is `https://api.moonshot.ai/v1`, and the chat completions endpoint relative to that base URL is `/chat/completions`.
169+
170+
### Agent Model Used
171+
172+
- GPT-5 Codex
173+
174+
### Completion Notes
175+
176+
- Draft only. No runtime implementation has been made in this story yet.
177+
178+
### File List
179+
180+
| File | Action |
181+
|------|--------|
182+
| `docs/stories/epic-184-kimi-provider/EPIC-184-KIMI-K2-5-PROVIDER.md` | Created |
183+
| `docs/stories/epic-184-kimi-provider/STORY-184.1-OPENAI-COMPATIBLE-KIMI-PROVIDER.md` | Created |
184+
185+
## Change Log
186+
187+
| Data | Agente | Mudança |
188+
|------|--------|---------|
189+
| 2026-05-08 | @sm / Codex | Epic/story draft criados a partir do issue #184, leitura do provider factory atual e documentação oficial Kimi API. |

0 commit comments

Comments
 (0)