Metadata-Version: 2.4
Name: agentops-rpc
Version: 0.1.0
Summary: Shared Pydantic wire types for AgentOps SDK ↔ controlplane RPC.
Author: Komodor Ltd.
License-Expression: LicenseRef-Komodor-Proprietary
Project-URL: Homepage, https://agentops.komodor.com
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Dynamic: license-file

# agentops-rpc

Shared Pydantic wire types for the AgentOps SDK and controlplane.

Both the SDK (`komodor-agentops`) and the controlplane import models from this
package, giving build-time (mypy) and runtime (Pydantic v2) type safety across
the wire boundary.

## Install

```bash
pip install agentops-rpc
```

## Quick Start

```python
from agentops_rpc import RunEventIn, IngestRunEventsRequest, HOOK_EVENT_TYPE_MAP

event = RunEventIn(
    event_type="span.started",
    span_id="span_abc",
    kind="tool",
    name="Bash",
    hook_event_type="tool.start",
)
event.model_dump()  # JSON-safe dict

request = IngestRunEventsRequest(worker_id="wrk_1", events=[event])
```

## Exported Models

### types.py -- Literal type aliases

| Type | Values |
|------|--------|
| `EventType` | `run.started`, `run.completed`, `run.failed`, `span.started`, `span.ended`, `message.created`, `log.created`, `token.created`, `custom.created`, `output.updated` |
| `RunStatus` | `queued`, `claimed`, `running`, `succeeded`, `failed` |
| `SpanKind` | `agent`, `llm`, `tool`, `chain`, `generation` |
| `HookEventName` | `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `SubagentStart`, `SubagentStop`, `Notification`, `Stop`, `SessionEnd`, `PermissionRequest`, `PreCompact`, `PostCompact` |
| `HookEventType` | `session.start`, `prompt.submit`, `tool.start`, `tool.end`, `tool.error`, `subagent.start`, `subagent.end`, `notification`, `session.stop`, `compaction.start`, `compaction.end` |
| `AgentStatus` | `online`, `offline` |
| `RunTransport` | `polling`, `api_sync`, `api_sse`, `a2a` |

### events.py -- Event ingest models

- `RunEventIn` -- unified event sent SDK -> controlplane
- `TraceEventIn`, `LogEventIn` -- structured events for DB tables
- `IngestRunEventsRequest` / `IngestRunEventsResponse`
- `BatchEventsRequest`
- `TraceEventResponse`, `LogEventResponse`, `RunMessageResponse`

### runs.py -- Run lifecycle models

- `CreateRunRequest`, `RunSummary`, `RunDetail`, `RunJob`
- `PollNextRunRequest`, `ClaimRunResponse`
- `StartRunRequest`, `StartRunDirectRequest`
- `CompleteRunRequest`, `FailRunRequest`, `UpdateRunOutputRequest`
- `AddRunMessageRequest`
- `InvokeAgentRequest` / `InvokeAgentResponse`
- `WorkerInvokeRequest` / `WorkerInvokeResponse`

### agents.py -- Agent registration models

- `AgentManifest`, `HeartbeatRequest`, `HeartbeatResponse`
- `AgentInstanceResponse`

### hook_types.py -- Hook event mapping

- `HOOK_EVENT_TYPE_MAP` -- maps Claude Code `HookEventName` to `HookEventType`

### a2a.py -- A2A protocol wire types

- `A2AMessage`, `A2AMessagePart`
- `A2AMessageRequest`, `A2ATaskResponse`

## Type Safety Guarantees

| Layer | Protection |
|-------|-----------|
| Build-time (mypy) | SDK and controlplane import the same Pydantic models -- field mismatches caught at type-check |
| Runtime (Pydantic) | Every event validated at construction and at API boundary |
| Wire (JSON) | `model_dump()` / `model_validate()` guarantee JSON matches schema |
| Hook events | `HookEventType` literal -- typos fail both type-check and runtime |

## Dependencies

Only `pydantic>=2.0`. Zero internal dependencies.
