# surajdusane/tv-agent architecture

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

- Interactive diagram: https://gitdiagram.com/surajdusane/tv-agent
- Repository: https://github.com/surajdusane/tv-agent

## Overview

##### Project Type and Purpose
- Type: Python-based AI-powered controller for Android TV.
- Purpose: Accept natural-language commands, plan a sequence of actions via AI agents, and execute them on an Android TV device or simulate via test tools.
- Key Indicators:
– agent_tools/ directory (specialized tool modules)
– main.py as the orchestrator
– config.json for device settings
– External integrations (Groq API, YouTube, JustWatch, ADB)

##### File Structure
- Top-level files:
– main.py: entry point, initializes agent, state, workflow.
– auto.py / uv.lock: build/deployment scripts (optional).
– config.json / .env.example: runtime configuration / secrets.
– model/groq_model.py: AI model abstraction.
– tools.json: mapping of tool names to modules.
- Directories:
– agent_tools/: each script is a “tool” that performs one function (get_key, send_link, get_recommendations, etc.).
– androidtv_remote_certs/: certificates for secure ADB connection.
– setup/: test scripts for local simulation.
- Patterns:
– Agent-orchestration pattern (Planner + Tool executors).
– Modular micro-services style within a single process.

##### README for Architecture Details
- Core Components described: Planner Agent, Task Executors (tools).
- Workflow: natural language → Planner → sequence of tool executions → TV control.
- External Services: Groq for AI inference, YouTube for videos, JustWatch for platform info, ADB for remote control.

##### Main Components and Their Relationships
a. Components:
1. User Interface (CLI / Text or Voice input)
2. Orchestrator (main.py)
– Planner Agent (LangGraph)
– State Manager (current_task, task_number)
– Tool Dispatcher (reads tools.json)
3. Tool Modules (agent_tools/*.py)
– get_key, send_key, get_youtube_query, get_youtube_link, send_link, get_platform, get_recommendations, set_show
4. AI/DL Model Layer
– model/groq_model.py (Groq API wrapper)
5. Configuration & Credentials
– config.json (TV IP, certificates)
– .env (GROQ_API_KEY)
6. External Systems
– Groq API
– YouTube / YouTube Data API
– JustWatch API or scraping
– Android TV Device (via ADB over network)
7. Local Simulation/Test Harness
– setup/test.py, setup/test2.py

1. User → CLI Interface → Orchestrator
2. Orchestrator → Planner Agent
3. Planner Agent → Tool Dispatcher → individual Tool Modules
4. Tool Modules ↔ AI/DL Model Layer (for NLP, embeddings)
5. Tool Modules → External APIs (Groq, YouTube, JustWatch)
6. Tool Modules → Android TV Device (via ADB SSL connection)
7. Tool Modules → State Manager → Orchestrator → next step
8. Orchestrator → final output to User

c. Architectural Patterns & Principles
- Agent-orchestration (Planner) separating planning from execution.
- Single Responsibility: each tool does one thing.
- Configuration-driven wiring (tools.json).
- Dependency injection of API keys and device credentials.

d. Key Technologies & Frameworks
- Python 3.12+
- LangGraph (agent framework)
- Groq API (model inference)
- androidtvremote2 / ADB over TLS
- JustWatch integration
- YouTube Data API
- uv (lockfile, sync, run)

##### Detail Without Overthinking
- Configuration feeds (tools.json) into the Dispatcher.
- Two modes of TV control: real device (ADB + certs) vs simulation (setup scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    CLI["CLI Interface"]:::internal
    User -->|issues command| CLI

    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        Orchestrator["Orchestrator (main.py)"]:::internal
        Planner["Planner Agent (LangGraph)"]:::internal
        Dispatcher["State Manager / Tool Dispatcher (tools.json)"]:::internal
    end
    CLI -->|invokes| Orchestrator
    Orchestrator -->|uses| Planner
    Orchestrator -->|reads| Dispatcher

    %% Tool Executors
    subgraph "Tool Executors" 
        getKey["get_key Tool"]:::internal
        sendKey["send_key Tool"]:::internal
        ytQuery["get_youtube_query Tool"]:::internal
        ytLink["get_youtube_link Tool"]:::internal
        sendLink["send_link Tool"]:::internal
        getPlatform["get_platform Tool"]:::internal
        getRec["get_recommendations Tool"]:::internal
        setShow["set_show Tool"]:::internal
    end
    Planner -->|dispatches| getKey
    Planner -->|dispatches| sendKey
    Planner -->|dispatches| ytQuery
    Planner -->|dispatches| ytLink
    Planner -->|dispatches| sendLink
    Planner -->|dispatches| getPlatform
    Planner -->|dispatches| getRec
    Planner -->|dispatches| setShow

    %% AI/DL Model Layer
    Model["AI Model Layer (model/groq_model.py)"]:::internal
    getKey -->|calls| Model
    sendKey -->|calls| Model
    ytQuery -->|calls| Model
    ytLink -->|calls| Model
    sendLink -->|calls| Model
    getPlatform -->|calls| Model
    getRec -->|calls| Model
    setShow -->|calls| Model

    %% Configuration & Credentials
    subgraph "Configuration & Credentials"
        Config["config.json"]:::config
        Env[".env.example"]:::config
        CertCrt["client.crt"]:::config
        CertKey["client.key"]:::config
    end
    Orchestrator -->|loads| Config
    Orchestrator -->|loads| Env
    Orchestrator -->|loads| CertCrt
    Orchestrator -->|loads| CertKey

    %% External Services
    subgraph "External Services"
        GroqAPI["Groq API"]:::cloud
        YouTube["YouTube Data API"]:::cloud
        JustWatch["JustWatch API"]:::cloud
    end
    Model -->|https| GroqAPI
    ytLink -->|https| YouTube
    getRec -->|https| JustWatch

    %% Android TV Device
    Device["Android TV Device (ADB over TLS)"]:::device
    sendKey -->|ADB over TLS| Device
    sendLink -->|ADB over TLS| Device
    setShow -->|ADB over TLS| Device

    %% Test Harness (Simulation)
    subgraph "Local Simulation/Test Harness" 
        direction TB
        style Test fill:none,stroke-dashed:#aaa,stroke-width:1
        Test1["setup/test.py"]:::test
        Test2["setup/test2.py"]:::test
    end
    Planner -.->|simulate| Test1
    Planner -.->|simulate| Test2

    %% Final Output
    Orchestrator -->|returns result| CLI
    CLI -->|displays| User

    %% Click Events
    click Orchestrator "https://github.com/surajdusane/tv-agent/blob/main/main.py"
    click Planner "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/planner.py"
    click Dispatcher "https://github.com/surajdusane/tv-agent/blob/main/tools.json"
    click getKey "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/get_key.py"
    click sendKey "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/send_key.py"
    click ytQuery "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/get_youtube_query.py"
    click ytLink "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/get_youtube_link.py"
    click sendLink "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/send_link.py"
    click getPlatform "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/get_platform.py"
    click getRec "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/get_recommendations.py"
    click setShow "https://github.com/surajdusane/tv-agent/blob/main/agent_tools/set_show.py"
    click Model "https://github.com/surajdusane/tv-agent/blob/main/model/groq_model.py"
    click Config "https://github.com/surajdusane/tv-agent/blob/main/config.json"
    click Env "https://github.com/surajdusane/tv-agent/blob/main/.env.example"
    click CertCrt "https://github.com/surajdusane/tv-agent/blob/main/androidtv_remote_certs/client.crt"
    click CertKey "https://github.com/surajdusane/tv-agent/blob/main/androidtv_remote_certs/client.key"
    click Test1 "https://github.com/surajdusane/tv-agent/blob/main/setup/test.py"
    click Test2 "https://github.com/surajdusane/tv-agent/blob/main/setup/test2.py"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#3399ff
    classDef external fill:#e0e0e0,stroke:#888888
    classDef config fill:#fff2cc,stroke:#d6b656
    classDef cloud fill:#d9d9d9,stroke:#777777
    classDef device fill:#ccffcc,stroke:#2d862d
    classDef test fill:#f0f0f0,stroke:#aaaaaa,stroke-dasharray: 5 5
```
