# myttyyytytyyttt/polyagent architecture

> Architecture diagram of the GitHub repository myttyyytytyyttt/polyagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/myttyyytytyyttt/polyagent
- Repository: https://github.com/myttyyytytyyttt/polyagent

## Overview

##### Project Type and Purpose
- PolyAgent is a Python-based agent framework and CLI tool for autonomous trading on Polymarket.
- It combines AI prompt engineering, Retrieval-Augmented Generation (RAG), real-time data connectors, and blockchain interactions.

##### File Structure
- Top-level modules:
- agents/           ← Core application logic and AI agent workflows
– application/    ← Agent orchestration: creator, executor, cron jobs, trade runner, prompts
– connectors/     ← Standardized interfaces to external data sources & APIs
– polymarket/     ← Polymarket-specific API clients (Gamma, Polymarket DEX)
– utils/          ← Shared utilities and Pydantic models
- scripts/            ← CLI entrypoint, server, Docker orchestration
- Dockerfile, .github/, CI workflows, tests/

##### Extract Architecture Insights from README
- Modular “connectors” layer abstracts Chroma vector DB, news, web search, and Polymarket APIs.
- “application” layer composes AI agents to fetch data, build prompts, analyze markets, and execute trades.
- Scripts provide end-user CLI and Dockerized deployment.
- External dependencies: OpenAI LLM, NewsAPI, Search API, Polymarket Gamma API, Polygon wallet/blockchain.

A. User Interface & Orchestration
1. CLI / scripts/python/cli.py
2. Docker/ bash scripts for build & dev
B. Agent Application Layer (agents/application)
1. Creator – instantiates agent workflows
2. Cron – scheduling & periodic triggers
3. Executor – runs AI pipelines & RAG loops
4. Trade – finalizes and sends orders
5. Prompts – prompt templates & engineering
C. Connectors Layer (agents/connectors & agents/polymarket)
1. ChromaConnector – vector DB storage & retrieval
2. NewsConnector – NewsAPI feed ingestion
3. SearchConnector – real-time web search
4. GammaMarketClient – Polymarket metadata & markets
5. PolymarketClient – order creation, signing, execution
D. Data Models & Utilities (agents/utils)
– Pydantic models for Market, Event, Trade, etc.
– Common helper functions
1. OpenAI LLM endpoint
2. NewsAPI
3. Search engine API
4. Polymarket Gamma API
5. Polygon Blockchain / Wallet
F. Data Stores
– Local vector store (Chroma DB)
– Environment variables (.env)

##### Relationships & Data Flow
- User invokes CLI/server → triggers Agent Creator/Executor.
- Executor calls Connectors to fetch:
- Market metadata (GammaMarketClient)
- Historical data & news (NewsConnector)
- Web search results (SearchConnector)
- RAG vector queries (ChromaConnector)
- Data models unify fetched data (agents/utils/objects.py).
- Executor & Prompts compose LLM requests → OpenAI API.
- Analysis output → Trade module builds order → PolymarketClient signs & sends to Blockchain.
- Cron scheduler can re-invoke workflows per ANALYSIS_DELAY_SECONDS.
- Docker container encapsulates the entire runtime with environment variables.

##### Architectural Patterns & Principles
- Layered modular design: UI → Application → Connectors → External.
- Dependency inversion: connectors implement standard interfaces.
- Pydantic for data validation & typing.
- Separation of concerns: trading logic decoupled from data retrieval.
- Configurable via environment variables and Docker.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI & Orchestration"
        CLI["CLI (cli.py)"]:::internal
        Server["Server (server.py)"]:::internal
    end

    subgraph "Infrastructure"
        Dockerfile["Dockerfile"]:::infra
        BuildDocker["build-docker.sh"]:::infra
        RunDockerDev["run-docker-dev.sh"]:::infra
        RunDocker["run-docker.sh"]:::infra
        StartDev["start-dev.sh"]:::infra
    end

    subgraph "Application Layer (agents/application)"
        Creator["Creator"]:::internal
        Cron["Cron Scheduler"]:::internal
        Executor["Executor"]:::internal
        Trade["Trade Runner"]:::internal
        Prompts["Prompts"]:::internal
    end

    subgraph "Connectors Layer"
        Chroma["ChromaConnector"]:::internal
        News["NewsConnector"]:::internal
        Search["SearchConnector"]:::internal
        Gamma["GammaMarketClient"]:::internal
        PMClient["PolymarketClient"]:::internal
    end

    subgraph "Utilities (agents/utils)"
        Models["Data Models"]:::internal
        Utils["Shared Utilities"]:::internal
    end

    subgraph "Data Stores"
        DB[(Chroma DB)]:::datastore
        Env[".env"]:::datastore
    end

    subgraph "External Services"
        LLM["OpenAI LLM"]:::external
        NewsAPI["NewsAPI"]:::external
        SearchAPI["Search API"]:::external
        GammaAPI["Polymarket Gamma API"]:::external
        Blockchain["Polygon Blockchain"]:::external
    end

    CLI --> Creator
    Server --> Creator
    Creator --> Executor
    Cron -.-> Executor
    Executor --> Chroma
    Executor --> News
    Executor --> Search
    Executor --> Gamma
    Executor --> Models
    Executor --> Prompts
    Prompts --> LLM
    Chroma --> DB
    News --> NewsAPI
    Search --> SearchAPI
    Gamma --> GammaAPI
    Executor --> Trade
    Trade --> PMClient
    PMClient --> Blockchain
    Env --> Creator
    Env --> Executor
    Env --> PMClient

    click CLI "https://github.com/myttyyytytyyttt/polyagent/blob/main/scripts/python/cli.py"
    click Server "https://github.com/myttyyytytyyttt/polyagent/blob/main/scripts/python/server.py"
    click Dockerfile "https://github.com/myttyyytytyyttt/polyagent/tree/main/Dockerfile"
    click BuildDocker "https://github.com/myttyyytytyyttt/polyagent/blob/main/scripts/bash/build-docker.sh"
    click RunDockerDev "https://github.com/myttyyytytyyttt/polyagent/blob/main/scripts/bash/run-docker-dev.sh"
    click RunDocker "https://github.com/myttyyytytyyttt/polyagent/blob/main/scripts/bash/run-docker.sh"
    click StartDev "https://github.com/myttyyytytyyttt/polyagent/blob/main/scripts/bash/start-dev.sh"
    click Creator "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/application/creator.py"
    click Cron "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/application/cron.py"
    click Executor "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/application/executor.py"
    click Trade "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/application/trade.py"
    click Prompts "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/application/prompts.py"
    click Chroma "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/connectors/chroma.py"
    click News "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/connectors/news.py"
    click Search "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/connectors/search.py"
    click Gamma "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/polymarket/gamma.py"
    click PMClient "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/polymarket/polymarket.py"
    click Models "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/utils/objects.py"
    click Utils "https://github.com/myttyyytytyyttt/polyagent/blob/main/agents/utils/utils.py"

    classDef internal fill:#D0E1F9,stroke:#0366d6,color:#0366d6
    classDef datastore fill:#F9EBD0,stroke:#d68c06,color:#d68c06
    classDef external fill:#CFF9D1,stroke:#059669,color:#059669
    classDef infra fill:#E0E0E0,stroke:#6b7280,color:#374151
```
