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

pip install relationalai-agent-shared

Usage

Import Event Types

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

Import ECS Components

from relationalai_agent_shared.ecs import Concept, Relationship, Source

Import Agent Contracts

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.