Skip to content

Commit 259e278

Browse files
grokifyclaude
grokify
and
claude
committed
docs: archive AX integration design documents
Move completed design docs to docs/design/archive/: - ax-integration.md (technical design) - FEAT_AX_PLAN.md (implementation tracker) - FEAT_AX_PRD.md (product requirements) These documents served their purpose during the AX integration implementation (omnivoice-core v0.8.0, elevenlabs-go v0.10.0, omnivoice-deepgram v0.5.0) and are preserved for historical reference. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 1c0da43 commit 259e278

3 files changed

Lines changed: 1255 additions & 0 deletions

File tree

‎docs/design/archive/FEAT_AX_PLAN.md‎

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
# AX Integration Implementation Plan
2+
3+
**Feature:** Agent Experience (AX) Integration
4+
**Status:** In Progress
5+
**Author:** @johnwang
6+
**Created:** 2024-04-03
7+
**Last Updated:** 2024-04-03
8+
9+
## Overview
10+
11+
This document tracks the implementation of AX integration across omnivoice-core, omnivoice, and elevenlabs-go repositories.
12+
13+
**Related Documents:**
14+
15+
- [PRD](./FEAT_AX_PRD.md) — Goals and requirements
16+
- [Design](./ax-integration.md) — Technical architecture
17+
18+
## Progress Tracker
19+
20+
| Phase | Status | Started | Completed | Notes |
21+
|-------|--------|---------|-----------|-------|
22+
| Phase 1: Core Resilience | 🟢 Complete | 2024-04-03 | 2024-04-03 | 44 tests passing |
23+
| Phase 2: AX Bridge | 🟢 Complete | 2024-04-03 | 2024-04-03 | Classifier + retry in TTS provider |
24+
| Phase 3: Smart Fallback | 🟢 Complete | 2024-04-03 | 2024-04-03 | TTS + STT fallback tests |
25+
| Phase 4: elevenlabs-go | 🟢 Complete | 2024-04-03 | 2024-04-03 | ax/omnivoice.go helpers |
26+
| Phase 5: Integration Testing | 🟢 Complete | 2024-04-03 | 2024-04-03 | 8 integration tests + 14 benchmarks |
27+
| Phase 6: Documentation | 🟢 Complete | 2024-04-03 | 2024-04-03 | CHANGELOGs + release notes |
28+
29+
---
30+
31+
## Phase 1: Core Resilience Package
32+
33+
**Repository:** `github.com/plexusone/omnivoice-core`
34+
**Location:** `resilience/`
35+
**Duration:** 1 week
36+
37+
### Tasks
38+
39+
| Task | File | Status | Description |
40+
|------|------|--------|-------------|
41+
| 1.1 | `resilience/doc.go` | ✅ Done | Package documentation |
42+
| 1.2 | `resilience/category.go` | ✅ Done | Error category constants |
43+
| 1.3 | `resilience/error.go` | ✅ Done | ErrorInfo and ProviderError types |
44+
| 1.4 | `resilience/classifier.go` | ✅ Done | ErrorClassifier interface |
45+
| 1.5 | `resilience/retry.go` | ✅ Done | Retry logic with generics |
46+
| 1.6 | `resilience/backoff.go` | ✅ Done | Backoff strategies |
47+
| 1.7 | `resilience/retry_test.go` | ✅ Done | Retry unit tests |
48+
| 1.8 | `resilience/backoff_test.go` | ✅ Done | Backoff unit tests |
49+
| 1.9 | `resilience/error_test.go` | ✅ Done | Error type tests |
50+
| 1.10 | `resilience/category_test.go` | ✅ Done | Category unit tests |
51+
52+
### Deliverables
53+
54+
- [x] `resilience` package with full test coverage (44 tests)
55+
- [x] Error categorization system (8 categories)
56+
- [x] Retry logic with configurable backoff
57+
- [x] Documentation (doc.go with examples)
58+
59+
### API Design
60+
61+
```go
62+
// Category constants
63+
const (
64+
CategoryTransient ErrorCategory = "transient"
65+
CategoryRateLimit ErrorCategory = "rate_limit"
66+
CategoryValidation ErrorCategory = "validation"
67+
CategoryAuth ErrorCategory = "auth"
68+
CategoryNotFound ErrorCategory = "not_found"
69+
CategoryServer ErrorCategory = "server"
70+
CategoryQuota ErrorCategory = "quota"
71+
CategoryUnknown ErrorCategory = "unknown"
72+
)
73+
74+
// ErrorInfo - metadata about an error
75+
type ErrorInfo struct {
76+
Category ErrorCategory
77+
Retryable bool
78+
Code string
79+
Message string
80+
Suggestion string
81+
RetryAfter time.Duration
82+
}
83+
84+
// ProviderError - wraps provider errors with context
85+
type ProviderError struct {
86+
Provider string
87+
Op string
88+
Err error
89+
Info ErrorInfo
90+
}
91+
92+
// ErrorClassifier - interface for provider-specific classification
93+
type ErrorClassifier interface {
94+
Classify(err error) ErrorInfo
95+
}
96+
97+
// RetryConfig - retry behavior configuration
98+
type RetryConfig struct {
99+
MaxAttempts int
100+
InitialDelay time.Duration
101+
MaxDelay time.Duration
102+
Multiplier float64
103+
Jitter float64
104+
}
105+
106+
// Retry - execute with retries
107+
func Retry(ctx context.Context, cfg RetryConfig, fn func() error) error
108+
109+
// RetryWithResult - execute with retries, return result
110+
func RetryWithResult[T any](ctx context.Context, cfg RetryConfig, fn func() (T, error)) (T, error)
111+
```
112+
113+
---
114+
115+
## Phase 2: AX Bridge
116+
117+
**Repository:** `github.com/plexusone/elevenlabs-go`
118+
**Location:** `omnivoice/`
119+
**Duration:** 1 week
120+
**Blocked by:** Phase 1
121+
122+
### Tasks
123+
124+
| Task | File | Status | Description |
125+
|------|------|--------|-------------|
126+
| 2.1 | `omnivoice/classifier.go` | ✅ Done | Error classifier using ax + HTTP status |
127+
| 2.2 | `omnivoice/classifier_test.go` | ✅ Done | Classifier unit tests (7 test cases) |
128+
| 2.3 | `omnivoice/tts/provider.go` | ✅ Done | TTS provider with retry + classification |
129+
| 2.4 | N/A | ⏭️ Deferred | Metrics collection (Phase 5) |
130+
| 2.5 | N/A | ⏭️ Deferred | STT provider with retry (same pattern as TTS) |
131+
132+
### Deliverables
133+
134+
- [x] ElevenLabs error classifier (`omnivoice.Classifier`)
135+
- [x] Retry logic in TTS provider with AX classification
136+
- [x] `WithRetryConfig` and `WithOnRetry` options
137+
- [ ] Metrics collection for goal measurement (deferred to Phase 5)
138+
139+
---
140+
141+
## Phase 3: Smart Fallback
142+
143+
**Repository:** `github.com/plexusone/omnivoice-core`
144+
**Location:** `tts/`, `stt/`
145+
**Duration:** 0.5 week
146+
**Blocked by:** Phase 1
147+
148+
### Tasks
149+
150+
| Task | File | Status | Description |
151+
|------|------|--------|-------------|
152+
| 3.1 | `tts/tts.go` | ✅ Done | Smart fallback (permanent errors only) |
153+
| 3.2 | `stt/stt.go` | ✅ Done | Smart fallback (permanent errors only) |
154+
| 3.3 | `tts/fallback_test.go` | ✅ Done | Fallback behavior tests (4 test cases) |
155+
| 3.4 | `stt/fallback_test.go` | ✅ Done | Fallback behavior tests (4 test cases) |
156+
157+
### Deliverables
158+
159+
- [x] Fallback only on permanent (non-retryable) errors
160+
- [x] `shouldFallback()` function using `resilience.IsProviderError`
161+
- [x] Tests for Synthesize and SynthesizeStream fallback
162+
- [x] Tests for Transcribe and TranscribeStream fallback
163+
164+
---
165+
166+
## Phase 4: elevenlabs-go Enhancements
167+
168+
**Repository:** `github.com/plexusone/elevenlabs-go`
169+
**Location:** `ax/`
170+
**Duration:** 0.5 week
171+
172+
### Tasks
173+
174+
| Task | File | Status | Description |
175+
|------|------|--------|-------------|
176+
| 4.1 | `ax/omnivoice.go` | ✅ Done | Helper functions for OmniVoice |
177+
| 4.2 | `ax/omnivoice_test.go` | ✅ Done | Helper tests (17 test cases) |
178+
179+
### Deliverables
180+
181+
- [x] `CategoryForCode()` - Maps AX error codes to resilience.ErrorCategory
182+
- [x] `IsRetryableCode()` - Checks if an AX code is retryable
183+
- [x] `SuggestionForCode()` - Returns helpful suggestions for each code
184+
- [x] `OperationRequiredFields()` - Returns required fields for 10 operations
185+
- [x] `ToErrorInfo()` - Converts AX code to resilience.ErrorInfo
186+
- [x] `ClassifyHTTPStatus()` - Classifies HTTP status codes
187+
- [x] `AllCategories()` - Lists all error categories
188+
- [x] `CodesByCategory()` - Gets codes by category
189+
190+
---
191+
192+
## Phase 5: Integration Testing
193+
194+
**Duration:** 1 week
195+
**Blocked by:** Phases 1-4
196+
197+
### Tasks
198+
199+
| Task | Description | Status |
200+
|------|-------------|--------|
201+
| 5.1 | Mock ElevenLabs API server | ⚪ TODO |
202+
| 5.2 | Rate limit simulation tests | ⚪ TODO |
203+
| 5.3 | Validation error tests | ⚪ TODO |
204+
| 5.4 | Fallback scenario tests | ⚪ TODO |
205+
| 5.5 | Performance benchmarks | ⚪ TODO |
206+
| 5.6 | Metrics validation | ⚪ TODO |
207+
208+
### Test Scenarios
209+
210+
| Scenario | Expected Behavior | Validates Goal |
211+
|----------|-------------------|----------------|
212+
| Rate limit (429) | Retry with backoff, succeed | G1 |
213+
| Auth error (401) | No retry, return immediately | G4 |
214+
| Missing required field | Caught pre-flight | G2 |
215+
| Server error (500) | Retry with backoff | G1 |
216+
| Permanent error + fallback | Switch provider | G4 |
217+
| Retryable error + retry succeeds | No fallback | G4 |
218+
219+
### Benchmarks
220+
221+
| Benchmark | Target |
222+
|-----------|--------|
223+
| Successful operation overhead | <5ms |
224+
| Error classification | <1ms |
225+
| Retry decision | <0.1ms |
226+
227+
---
228+
229+
## Phase 6: Documentation & Release
230+
231+
**Duration:** 0.5 week
232+
**Blocked by:** Phases 1-5
233+
234+
### Tasks
235+
236+
| Task | Description | Status |
237+
|------|-------------|--------|
238+
| 6.1 | Update omnivoice docs | ✅ Done |
239+
| 6.2 | Update omnivoice-core docs | ✅ Done |
240+
| 6.3 | Write migration guide | ✅ Done |
241+
| 6.4 | Update CHANGELOGs | ✅ Done |
242+
| 6.5 | Create release notes | ✅ Done |
243+
| 6.6 | Tag releases | ⚪ TODO |
244+
245+
### Deliverables
246+
247+
- [x] elevenlabs-go CHANGELOG.md updated with v0.10.0 entry
248+
- [x] omnivoice-core CHANGELOG.md updated with v0.8.0 entry
249+
- [x] elevenlabs-go/docs/releases/v0.10.0.md release notes
250+
- [x] omnivoice-core/docs/releases/v0.8.0.md release notes
251+
- [x] Migration guides included in release notes
252+
- [ ] Tag omnivoice-core v0.8.0 (after removing replace directive)
253+
- [ ] Tag elevenlabs-go v0.10.0 (after omnivoice-core is tagged)
254+
255+
---
256+
257+
## Goal Validation
258+
259+
After implementation, run experiments to validate goals:
260+
261+
| Goal | Validation Method | Target |
262+
|------|-------------------|--------|
263+
| G1: Auto-recovery | Run videoascode batch with rate limits | >70% recovery |
264+
| G2: Validation savings | Intentionally invalid requests | >80% caught |
265+
| G3: Batch completion | 100-slide batch with failures | >90% complete |
266+
| G4: Error context | Audit all error returns | 100% have category |
267+
| G5: Latency | Benchmark successful operations | <5ms overhead |
268+
| G6: Compatibility | Run existing tests | 0 failures |
269+
270+
See [ax-spec/TASKS.md](https://github.com/plexusone/ax-spec/blob/main/TASKS.md) for detailed experiment protocols.
271+
272+
---
273+
274+
## Dependencies
275+
276+
```
277+
omnivoice-core/resilience (Phase 1)
278+
│
279+
├──────────────────────┐
280+
│ │
281+
▼ ▼
282+
omnivoice/providers/elevenlabs omnivoice-core/tts,stt
283+
(Phase 2) (Phase 3)
284+
│ │
285+
└──────────┬───────────┘
286+
│
287+
▼
288+
elevenlabs-go/ax
289+
(Phase 4)
290+
│
291+
▼
292+
Integration Testing
293+
(Phase 5)
294+
│
295+
▼
296+
Documentation & Release
297+
(Phase 6)
298+
```
299+
300+
---
301+
302+
## Rollback Plan
303+
304+
If issues are discovered post-release:
305+
306+
1. **Minor issues:** Patch release with fix
307+
2. **Major issues:**
308+
- Revert to previous version
309+
- Disable AX features via configuration flag
310+
- Investigate and fix in development
311+
312+
---
313+
314+
## Notes
315+
316+
### Implementation Notes
317+
318+
- Use generics for `RetryWithResult[T]` to avoid type assertions
319+
- Thread-safe metrics using `atomic` package
320+
- Preserve full error chain with `errors.Join` or wrapping
321+
- Context cancellation checked between retries
322+
323+
### Testing Notes
324+
325+
- Use table-driven tests for error classification
326+
- Mock time for deterministic backoff tests
327+
- Use httptest for mock API server
328+
- Benchmark with realistic payloads
329+
330+
---
331+
332+
## Changelog
333+
334+
| Date | Change |
335+
|------|--------|
336+
| 2024-04-03 | Initial plan created |
337+
| 2024-04-03 | Phase 1 completed (resilience package with 44 tests) |
338+
| 2024-04-03 | Phase 2 completed (AX classifier + retry in TTS provider) |
339+
| 2024-04-03 | Phase 3 completed (smart fallback in TTS + STT clients) |
340+
| 2024-04-03 | Phase 4 completed (ax/omnivoice.go helpers with 17 tests) |
341+
| 2024-04-03 | Phase 5 completed (8 integration tests + 14 benchmarks) |
342+
| 2024-04-03 | Phase 6 completed (CHANGELOGs + release notes for v0.8.0 and v0.10.0) |

0 commit comments

Comments
 (0)