Metadata-Version: 2.3
Name: relationalai-agent-shared
Version: 0.3.3
Summary: Shared types and contracts for the RelationalAI Agent API
Author: RelationalAI
Author-email: RelationalAI <support@relational.ai>
License: Apache-2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-ai-slim[anthropic,openai,openrouter,retries]>=1.20.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# RelationalAI Agent Shared

Shared types and contracts for the RelationalAI Agent API.

## Overview

This package provides common data structures, event types, and Pydantic models used across RelationalAI's agent ecosystem. It defines the contracts between agent clients and servers, including:

- **Event Types**: Streaming events for agent communication (StatusEvent, PlanEvent, ResultEvent, ErrorEvent, ExecuteCodeEvent)
- **ECS Components**: Entity-Component-System architecture for semantic modeling (Concept, Relationship, Source)
- **Agent Contracts**: Request/response models for agent interactions
- **Capability Configuration**: Control what capabilities agents can use (query, optimize, predict, visualize)
- **Quotas**: Resource limits for agent operations

## Installation

```bash
pip install relationalai-agent-shared
```

## Usage

### Import Event Types

```python
from relationalai_agent_shared import (
    StatusEvent,
    PlanEvent,
    ResultEvent,
    ErrorEvent,
    ExecuteCodeEvent,
    TaskStartEvent,
    TaskEndEvent,
)
```

### Import ECS Components

```python
from relationalai_agent_shared.ecs import Concept, Relationship, Source
```

### Import Agent Contracts

```python
from relationalai_agent_shared import (
    AskRequest,
    AgentContextItem,
    CapabilityConfig,
    Quotas,
)
```

## Key Features

### Streaming Events

The package defines a complete set of streaming events for real-time agent communication:

- **StatusEvent**: Progress updates during agent processing
- **PlanEvent**: Query plans and task breakdowns
- **ExecuteCodeEvent**: Generated code for client-side execution
- **ResultEvent**: Final results from agent operations
- **ErrorEvent**: Error details with context

### ECS (Entity-Component-System)

A columnar storage architecture for semantic models:

- **Concept**: Represents entities in your domain model
- **Relationship**: Defines connections between concepts
- **Source**: References to external data sources

## Requirements

- Python 3.11+
- pydantic >= 2.0.0
- pydantic-ai-slim >= 1.0.0

## License

Apache License 2.0 - see LICENSE file for details.

## Support

For questions and support, contact support@relational.ai or visit https://docs.relational.ai.
