AGENTS.html

<!-- BEGIN constitution-inheritance pointer (managed) -->
<h2 id="inherited-from-helix-constitution">INHERITED FROM Helix
Constitution</h2>
<p>This module is a submodule of a project that includes the Helix
Constitution submodule. All rules in <code>constitution/CLAUDE.md</code>
and the <code>constitution/Constitution.md</code> it references apply
unconditionally. Locate the constitution submodule from any arbitrary
nested depth using its <code>find_constitution.sh</code> helper.</p>
<p>Canonical reference:
https://github.com/HelixDevelopment/HelixConstitution
<!-- END constitution-inheritance pointer (managed) --> # AGENTS.md -
LLMProvider Module &gt; <strong>Base agent rules:</strong>
<code>HelixConstitution/AGENTS.md</code> — READ IT FIRST. &gt; All rules
in <code>HelixConstitution/AGENTS.md</code> apply unconditionally. &gt;
Rules below extend them and MUST NOT weaken any inherited clause.</p>
<h2 id="module-overview">Module Overview</h2>
<p><code>digital.vasic.llmprovider</code> is a generic, reusable Go
module providing LLM provider abstractions and utilities. It defines the
core <code>LLMProvider</code> interface and common patterns for building
LLM provider implementations, including circuit breakers, health
monitoring, retry logic, and lazy loading. The module is designed for
AI/LLM applications that need to integrate multiple LLM providers with
fault tolerance and observability.</p>
<p><strong>Module path</strong>: <code>digital.vasic.llmprovider</code>
<strong>Go version</strong>: 1.25.3+ <strong>Dependencies</strong>:
<code>digital.vasic.models</code>,
<code>github.com/sirupsen/logrus</code> <strong>Test
Dependencies</strong>: <code>github.com/stretchr/testify</code></p>
<h2 id="package-responsibilities">Package Responsibilities</h2>
<table>
<colgroup>
<col style="width: 29%" />
<col style="width: 19%" />
<col style="width: 51%" />
</colgroup>
<thead>
<tr>
<th>Package</th>
<th>Path</th>
<th>Responsibility</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>llmprovider</code></td>
<td><code>./</code></td>
<td>Core types: <code>LLMProvider</code> interface, circuit breaker,
health monitor, retry config, lazy provider, and associated utilities.
This is the only package.</td>
</tr>
</tbody>
</table>
<h2 id="dependency-graph">Dependency Graph</h2>
<pre><code>digital.vasic.models
    ↓
digital.vasic.llmprovider
    ↓
github.com/sirupsen/logrus</code></pre>
<h2 id="key-files">Key Files</h2>
<table>
<colgroup>
<col style="width: 40%" />
<col style="width: 60%" />
</colgroup>
<thead>
<tr>
<th>File</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>provider.go</code></td>
<td><code>LLMProvider</code> interface definition with
<code>Complete</code>, <code>CompleteStream</code>,
<code>HealthCheck</code>, <code>GetCapabilities</code>,
<code>ValidateConfig</code> methods</td>
</tr>
<tr>
<td><code>circuit_breaker.go</code></td>
<td>Circuit breaker implementation (503 lines) with
closed/open/half-open states, failure counting, timeout</td>
</tr>
<tr>
<td><code>health_monitor.go</code></td>
<td>Health monitoring (430 lines) with configurable thresholds,
intervals, status transitions</td>
</tr>
<tr>
<td><code>retry.go</code></td>
<td>Retry logic (226 lines) with exponential backoff, jitter, HTTP
status code detection</td>
</tr>
<tr>
<td><code>types.go</code></td>
<td>Empty file (types moved to models module)</td>
</tr>
<tr>
<td><code>circuit_breaker_test.go</code></td>
<td>Circuit breaker tests (585 lines)</td>
</tr>
<tr>
<td><code>health_monitor_test.go</code></td>
<td>Health monitor tests</td>
</tr>
<tr>
<td><code>retry_test.go</code></td>
<td>Retry logic tests</td>
</tr>
<tr>
<td><code>types_test.go</code></td>
<td>Empty test file</td>
</tr>
<tr>
<td><code>go.mod</code></td>
<td>Module definition and dependencies</td>
</tr>
<tr>
<td><code>CLAUDE.md</code></td>
<td>AI coding assistant instructions</td>
</tr>
<tr>
<td><code>README.md</code></td>
<td>User-facing documentation with quick start</td>
</tr>
</tbody>
</table>
<h2 id="agent-coordination-guide">Agent Coordination Guide</h2>
<h3 id="division-of-work">Division of Work</h3>
<p>When multiple agents work on this module simultaneously, divide work
by component categories:</p>
<ol type="1">
<li><strong>Interface Agent</strong> – Owns <code>LLMProvider</code>
interface definition and related methods. Changes affect all provider
implementations.</li>
<li><strong>Circuit Breaker Agent</strong> – Owns circuit breaker
implementation and <code>CircuitBreakerManager</code>. Affects fault
tolerance.</li>
<li><strong>Health Monitor Agent</strong> – Owns health monitoring,
thresholds, status transitions.</li>
<li><strong>Retry Logic Agent</strong> – Owns retry configuration,
exponential backoff, HTTP status detection.</li>
<li><strong>Lazy Provider Agent</strong> – Owns lazy initialization
pattern and deferred provider creation.</li>
</ol>
<h3 id="coordination-rules">Coordination Rules</h3>
<ul>
<li><strong><code>LLMProvider</code> interface changes</strong> require
coordination with all agents as this is the foundational interface.</li>
<li><strong>Circuit breaker behavior changes</strong> affect fault
tolerance across all providers.</li>
<li><strong>Health monitor thresholds</strong> affect provider health
detection and automatic failover.</li>
<li><strong>Retry logic changes</strong> affect error recovery and rate
limiting handling.</li>
<li><strong>Lazy provider changes</strong> affect initialization
patterns and startup performance.</li>
</ul>
<h3 id="safe-parallel-changes">Safe Parallel Changes</h3>
<p>These changes can be made simultaneously without coordination: -
Adding new methods to existing structs (if they don’t affect interface)
- Adding new configuration options with sensible defaults - Adding new
helper functions - Updating documentation - Adding new test cases -
Improving error messages or logging</p>
<h3 id="changes-requiring-coordination">Changes Requiring
Coordination</h3>
<ul>
<li>Modifying <code>LLMProvider</code> interface method signatures
(breaks all implementations)</li>
<li>Changing circuit breaker state machine logic (affects fault
tolerance)</li>
<li>Modifying health monitor status transition thresholds (affects
provider health detection)</li>
<li>Changing retry exponential backoff formula (affects error recovery
timing)</li>
<li>Modifying lazy provider initialization semantics (affects startup
behavior)</li>
</ul>
<h2 id="build-and-test-commands">Build and Test Commands</h2>
<div class="sourceCode" id="cb2"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Build all packages</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> build ./...</span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="co"># Run all tests with race detection</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test ./... <span class="at">-count</span><span class="op">=</span>1 <span class="at">-race</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="co"># Run unit tests only (short mode)</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test ./... <span class="at">-short</span></span>
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a><span class="co"># Run a specific test</span></span>
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test <span class="at">-v</span> <span class="at">-run</span> TestCircuitBreaker ./...</span>
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a><span class="co"># Format code</span></span>
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a><span class="ex">gofmt</span> <span class="at">-w</span> .</span>
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a><span class="co"># Vet code</span></span>
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> vet ./...</span>
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-19"><a href="#cb2-19" aria-hidden="true" tabindex="-1"></a><span class="co"># Check dependencies</span></span>
<span id="cb2-20"><a href="#cb2-20" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> mod tidy</span>
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> mod verify</span></code></pre></div>
<h2 id="commit-conventions">Commit Conventions</h2>
<p>Follow Conventional Commits with llmprovider scope:</p>
<pre><code>feat(llmprovider): add new method to LLMProvider interface for batch processing
feat(circuit): add configurable failure threshold to circuit breaker
feat(health): add degraded state to health monitor
feat(retry): add jitter to exponential backoff
fix(circuit): correct race condition in state transition
test(health): add edge case tests for health monitor thresholds
docs(llmprovider): update API reference for new methods
refactor(retry): extract common backoff calculation functions</code></pre>
<h2 id="thread-safety-and-concurrency">Thread Safety and
Concurrency</h2>
<ul>
<li><code>CircuitBreaker</code> uses <code>sync.RWMutex</code> for
thread-safe state management</li>
<li><code>HealthMonitor</code> uses atomic operations for status
updates</li>
<li><code>CircuitBreakerManager</code> is thread-safe for concurrent
provider management</li>
<li><code>RetryConfig</code> is immutable after creation</li>
<li><code>LazyProvider</code> uses <code>sync.Once</code> for
thread-safe lazy initialization</li>
<li>All exported methods are safe for concurrent use unless otherwise
documented</li>
</ul>
<h2 id="integration-notes">Integration Notes</h2>
<ul>
<li>This module depends on <code>digital.vasic.models</code> for
<code>LLMRequest</code>, <code>LLMResponse</code>,
<code>ProviderCapabilities</code> types</li>
<li>Provider implementations should import this module and implement the
<code>LLMProvider</code> interface</li>
<li>The module is designed for zero-dependency provider implementations
(implementations only need this module and models)</li>
<li>Circuit breaker and health monitor can be composed around any
<code>LLMProvider</code> implementation</li>
</ul>