How surajdusane/tv-agent works
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).