docs(ai-service): update readme with plugin protocol integration
Update AI service README to reflect the dual-service architecture (AI operations + plugin protocol) and complete integration guide. Architecture Updates: - Document both GitCaddyAIService and PluginService running on port 5000 - Add architecture diagram showing server's AI client and plugin manager connections - Clarify h2c (cleartext HTTP/2) transport for gRPC + REST on same port API Reference: - Add plugin protocol RPC methods (Initialize, HealthCheck, OnEvent, Shutdown) - Explain plugin lifecycle and health monitoring (30s intervals) - Document manifest-based capability declaration Integration Guide: - Split configuration into [ai] (operations) and [plugins.gitcaddy-ai] (lifecycle) - Explain how both sections work together for complete integration - Update client examples to use port 5000 (was 5051) - Add transport details and event subscription explanation This provides a complete picture of how the AI service integrates with the server as both an AI operations provider and a managed plugin.
This commit is contained in:
91
README.md
91
README.md
@@ -13,19 +13,30 @@ AI-powered code intelligence service for GitCaddy. Provides code review, documen
|
||||
|
||||
## Architecture
|
||||
|
||||
The AI service runs as a sidecar alongside the GitCaddy server. It exposes two gRPC services on the same port (HTTP/2 + HTTP/1.1):
|
||||
|
||||
- **GitCaddyAIService** - AI operations (review, triage, docs, chat) called by the server's AI client
|
||||
- **PluginService** - Plugin lifecycle protocol (initialize, health, events) managed by the server's external plugin manager
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ GitCaddy Server (Go) │
|
||||
│ └── AI Client (gRPC) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ GitCaddy AI Service (.NET 9) │ │
|
||||
│ │ ├── gRPC API │ │
|
||||
│ │ ├── MarketAlly.AIPlugin (Multi-provider AI) │ │
|
||||
│ │ └── License Validation │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
┌──────────────────────────────────────────────────────────────────────┐
|
||||
│ GitCaddy Server (Go) │
|
||||
│ ├── AI Client (gRPC) ──────────────── GitCaddyAIService │
|
||||
│ │ ReviewPullRequest, TriageIssue, │ │
|
||||
│ │ ExplainCode, GenerateDocumentation │ │
|
||||
│ │ │ │
|
||||
│ └── External Plugin Manager (gRPC) ─── PluginService │
|
||||
│ Initialize, HealthCheck (30s), │ │
|
||||
│ OnEvent, Shutdown ▼ │
|
||||
│ ┌──────────────────────────┐ │
|
||||
│ │ GitCaddy AI (.NET 9) │ │
|
||||
│ │ Port 5000 (h2c + HTTP) │ │
|
||||
│ │ ├── AI Providers │ │
|
||||
│ │ │ (Claude/OpenAI/ │ │
|
||||
│ │ │ Gemini) │ │
|
||||
│ │ └── License Validation │ │
|
||||
│ └──────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
@@ -94,7 +105,9 @@ Environment variable format: `AIService__DefaultProvider=Claude`
|
||||
|
||||
## API Reference
|
||||
|
||||
The service exposes a gRPC API defined in `protos/gitcaddy_ai.proto`.
|
||||
The service exposes two gRPC services on port 5000 (cleartext HTTP/2):
|
||||
|
||||
### AI Operations (`protos/gitcaddy_ai.proto`)
|
||||
|
||||
### Code Review
|
||||
|
||||
@@ -134,6 +147,21 @@ rpc ExecuteTask(ExecuteTaskRequest) returns (ExecuteTaskResponse);
|
||||
rpc Chat(stream ChatRequest) returns (stream ChatResponse);
|
||||
```
|
||||
|
||||
### Plugin Protocol (`protos/plugin.proto`)
|
||||
|
||||
The plugin protocol allows the GitCaddy server to manage this service as an external plugin:
|
||||
|
||||
```protobuf
|
||||
rpc Initialize(InitializeRequest) returns (InitializeResponse);
|
||||
rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
|
||||
rpc HealthCheck(PluginHealthCheckRequest) returns (PluginHealthCheckResponse);
|
||||
rpc GetManifest(GetManifestRequest) returns (PluginManifest);
|
||||
rpc OnEvent(PluginEvent) returns (EventResponse);
|
||||
rpc HandleHTTP(HTTPRequest) returns (HTTPResponse);
|
||||
```
|
||||
|
||||
The server calls `Initialize` on startup, `HealthCheck` every 30 seconds, `OnEvent` for subscribed events (e.g., `license:updated`), and `Shutdown` on server stop. The service declares its capabilities (routes, permissions, license tier) via the `PluginManifest` returned during initialization.
|
||||
|
||||
## Client Libraries
|
||||
|
||||
### .NET Client
|
||||
@@ -141,7 +169,7 @@ rpc Chat(stream ChatRequest) returns (stream ChatResponse);
|
||||
```csharp
|
||||
using GitCaddy.AI.Client;
|
||||
|
||||
var client = new GitCaddyAIClient("http://localhost:5051");
|
||||
var client = new GitCaddyAIClient("http://localhost:5000");
|
||||
|
||||
var response = await client.ReviewPullRequestAsync(new ReviewPullRequestRequest
|
||||
{
|
||||
@@ -159,7 +187,7 @@ Console.WriteLine(response.Summary);
|
||||
```go
|
||||
import ai "git.marketally.com/gitcaddy/gitcaddy-ai/go/gitcaddy-ai-client"
|
||||
|
||||
client, err := ai.NewClient("localhost:5051")
|
||||
client, err := ai.NewClient("localhost:5000")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
@@ -213,14 +241,43 @@ go generate
|
||||
|
||||
## Integration with GitCaddy Server
|
||||
|
||||
Add the AI client to your GitCaddy server configuration:
|
||||
Add both sections to the server's `app.ini`:
|
||||
|
||||
**1. AI client configuration** (how the server calls AI operations):
|
||||
|
||||
```ini
|
||||
[ai]
|
||||
ENABLED = true
|
||||
SERVICE_URL = http://localhost:5051
|
||||
SERVICE_URL = localhost:5000
|
||||
DEFAULT_PROVIDER = claude
|
||||
DEFAULT_MODEL = claude-sonnet-4-20250514
|
||||
CLAUDE_API_KEY = sk-ant-...
|
||||
```
|
||||
|
||||
See the [server README](https://git.marketally.com/gitcaddy/gitcaddy-server#ai-features-configuration) for the full `[ai]` reference.
|
||||
|
||||
**2. Plugin registration** (how the server manages the sidecar's lifecycle):
|
||||
|
||||
```ini
|
||||
[plugins]
|
||||
ENABLED = true
|
||||
HEALTH_CHECK_INTERVAL = 30s
|
||||
|
||||
[plugins.gitcaddy-ai]
|
||||
ENABLED = true
|
||||
ADDRESS = localhost:5000
|
||||
HEALTH_TIMEOUT = 5s
|
||||
SUBSCRIBED_EVENTS = license:updated
|
||||
```
|
||||
|
||||
With both sections configured, the server will:
|
||||
- Call AI operations (review, triage, etc.) via `[ai] SERVICE_URL`
|
||||
- Manage the sidecar's lifecycle via the plugin protocol on `[plugins.gitcaddy-ai] ADDRESS`
|
||||
- Health-check the sidecar every 30 seconds and log status changes
|
||||
- Dispatch subscribed events (e.g., license updates) to the sidecar in real-time
|
||||
|
||||
**Transport**: All communication uses cleartext HTTP/2 (h2c). The sidecar's Kestrel server is configured for `Http1AndHttp2` on port 5000, supporting both gRPC (HTTP/2) and REST (HTTP/1.1) on the same port.
|
||||
|
||||
## Support
|
||||
|
||||
- Documentation: https://docs.gitcaddy.com/ai
|
||||
|
||||
Reference in New Issue
Block a user