API Models

Pydantic models used in the GatheRing API.

Agent Models

AgentCreate

class AgentCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    role: Optional[str] = Field(None, max_length=100)
    provider: str = Field(default="anthropic")  # openai, anthropic, ollama
    model: str = Field(default="claude-sonnet-4-20250514")
    personality: Optional[PersonalityConfig] = None
    background: Optional[BackgroundConfig] = None
    config: Optional[AgentConfig] = None

AgentUpdate

class AgentUpdate(BaseModel):
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    role: Optional[str] = None
    model: Optional[str] = None
    personality: Optional[PersonalityConfig] = None
    config: Optional[AgentConfig] = None

AgentResponse

class AgentResponse(BaseModel):
    id: int
    name: str
    role: Optional[str]
    model: str
    personality: Optional[PersonalityConfig]
    config: Optional[AgentConfig]
    status: AgentStatus
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True

PersonalityConfig

class PersonalityConfig(BaseModel):
    traits: list[str] = Field(default_factory=list)
    communication_style: Optional[str] = "professional"
    languages: list[str] = Field(default_factory=lambda: ["English"])

AgentConfig

class AgentConfig(BaseModel):
    temperature: float = Field(default=0.7, ge=0, le=2)
    max_tokens: int = Field(default=4096, ge=1)
    tools: list[str] = Field(default_factory=list)

AgentStatus

class AgentStatus(str, Enum):
    IDLE = "idle"
    ACTIVE = "active"
    BUSY = "busy"
    OFFLINE = "offline"

Circle Models

CircleCreate

class CircleCreate(BaseModel):
    name: str = Field(..., pattern="^[a-z0-9-]+$", max_length=50)
    display_name: Optional[str] = Field(None, max_length=200)
    description: Optional[str] = None
    config: Optional[CircleConfig] = None

CircleResponse

class CircleResponse(BaseModel):
    id: int
    name: str
    display_name: Optional[str]
    description: Optional[str]
    config: Optional[CircleConfig]
    status: CircleStatus
    agent_count: int
    created_at: datetime

    class Config:
        from_attributes = True

CircleConfig

class CircleConfig(BaseModel):
    max_agents: int = Field(default=10, ge=1, le=50)
    conversation_mode: str = Field(default="round_robin")
    turn_timeout: int = Field(default=30, ge=1)
    max_turns_per_conversation: int = Field(default=50, ge=1)
    memory_scope: str = Field(default="circle")
    allow_tools: bool = True

CircleStatus

class CircleStatus(str, Enum):
    CREATED = "created"
    ACTIVE = "active"
    PAUSED = "paused"
    ARCHIVED = "archived"

Conversation Models

ConversationCreate

class ConversationCreate(BaseModel):
    circle_name: str
    topic: str = Field(..., min_length=1, max_length=500)
    agent_ids: list[int] = Field(..., min_items=1)
    initial_prompt: Optional[str] = None
    max_turns: int = Field(default=50, ge=1)

ConversationResponse

class ConversationResponse(BaseModel):
    id: int
    circle_id: int
    topic: str
    status: ConversationStatus
    turn_count: int
    created_at: datetime
    ended_at: Optional[datetime]

    class Config:
        from_attributes = True

ConversationAdvance

class ConversationAdvance(BaseModel):
    prompt: Optional[str] = None
    agent_id: Optional[int] = None

MessageResponse

class MessageResponse(BaseModel):
    id: int
    conversation_id: int
    agent_id: int
    agent_name: str
    content: str
    role: str
    created_at: datetime

    class Config:
        from_attributes = True

Workspace Models

WorkspaceInfo

class WorkspaceInfo(BaseModel):
    id: int
    path: str
    name: str
    git_enabled: bool
    current_branch: Optional[str]

FileInfo

class FileInfo(BaseModel):
    path: str
    name: str
    type: str  # "file" or "directory"
    size: Optional[int]
    modified_at: Optional[datetime]

FileContentclass FileContent(BaseModel):
    path: str
    content: str
    language: Optional[str]
    size: int

FileWrite

class FileWrite(BaseModel):
    content: str

GitStatus

class GitStatus(BaseModel):
    branch: str
    ahead: int
    behind: int
    staged: list[str]
    modified: list[str]
    untracked: list[str]
    deleted: list[str]

GitCommit

class GitCommit(BaseModel):
    hash: str
    short_hash: str
    message: str
    author: str
    date: datetime

GitStage

class GitStage(BaseModel):
    files: list[str]

GitCommitCreate

class GitCommitCreate(BaseModel):
    message: str = Field(..., min_length=1, max_length=500)

Memory Models

MemoryCreate

class MemoryCreate(BaseModel):
    agent_id: Optional[int] = None
    scope: MemoryScope
    scope_id: Optional[int] = None
    memory_type: MemoryType = MemoryType.FACT
    key: str = Field(..., max_length=200)
    value: str
    tags: list[str] = Field(default_factory=list)
    importance: float = Field(default=0.5, ge=0, le=1)

MemoryResponse

class MemoryResponse(BaseModel):
    id: int
    agent_id: Optional[int]
    scope: MemoryScope
    memory_type: MemoryType
    key: str
    value: str
    importance: float
    created_at: datetime

    class Config:
        from_attributes = True

MemorySearchResult

class MemorySearchResult(BaseModel):
    id: int
    key: str
    value: str
    similarity: float
    scope: MemoryScope

MemoryScope

class MemoryScope(str, Enum):
    GLOBAL = "global"
    CIRCLE = "circle"
    AGENT = "agent"
    CONVERSATION = "conversation"

MemoryType

class MemoryType(str, Enum):
    FACT = "fact"
    PREFERENCE = "preference"
    EXPERIENCE = "experience"
    SKILL = "skill"
    RELATIONSHIP = "relationship"

Dashboard Models

DashboardStats

class DashboardStats(BaseModel):
    total_agents: int
    active_agents: int
    total_circles: int
    active_circles: int
    conversations_today: int
    messages_today: int

ActivityItem

class ActivityItem(BaseModel):
    id: int
    type: str
    title: str
    description: Optional[str]
    agent_id: Optional[int]
    agent_name: Optional[str]
    circle_id: Optional[int]
    circle_name: Optional[str]
    timestamp: datetime

Common Models

PaginatedResponse

class PaginatedResponse(BaseModel, Generic[T]):
    items: list[T]
    total: int
    page: int
    page_size: int
    pages: int

ErrorResponse

class ErrorResponse(BaseModel):
    detail: str
    code: Optional[str] = None

ValidationErrorResponse

class ValidationErrorResponse(BaseModel):
    detail: list[ValidationErrorItem]


class ValidationErrorItem(BaseModel):
    loc: list[str]
    msg: str
    type: str