How devansh-236/kite_portfolio-ai-assistant works
Project type and purpose
• This is an open-source, CLI-driven multi-agent Python application for personalized portfolio analysis.
• It orchestrates a sequence of AI “agents” (preference collection, data fetching, analysis, suggestion, reporting) to produce Markdown reports.
• It integrates with two external services: Zerodha Kite Connect API (portfolio data) and Google Gemini AI (analysis).
File structure
• Top-level scripts & configs:
– main.py: the orchestrator/entrypoint
– Makefile: setup, test, run commands
– requirements.txt / .env.example: dependency & environment management
• Packages:
– agents/: one file per agent (single-responsibility modules)
– config/: settings.py reads environment variables
– kite_api/: connector.py wraps Kite Connect API calls
– utils/: api_handler.py (rate-limited Gemini calls) and auth.py (Kite token setup)
• Output directories (not in your tree but implied by README): reports/ and user_preferences/ for generated artifacts
Key architectural hints from the README
• Multi-Agent pipeline: UserPreference → PortfolioFetcher → DataAnalyzer → SuggestionEngine → ReportGenerator
• Config and authentication handled up-front (env vars, utils/auth.py)
• External API interactions abstracted into dedicated modules
• Reports saved locally in Markdown, user preferences saved as JSON
Main components & their relationships
1) CLI Orchestrator (main.py & Makefile commands)
2) Config Manager (config/settings.py)
3) Auth Module (utils/auth.py)
4) Agents (agents/):
– UserPreferenceAgent
– PortfolioFetcherAgent
– DataAnalyzerAgent
– SuggestionEngineAgent
– ReportGeneratorAgent
5) Kite Connect API (external service)
6) Google Gemini AI API (external service)
7) Utilities (utils/api_handler.py)
8) Local Storage: user_preferences/ (JSON), reports/ (Markdown)
b. Interactions & data flow:
• Startup: CLI Orchestrator reads config → sets up env via config/settings.py
• Auth step: utils/auth.py ↔ Kite Connect API to obtain access token
1. UserPreferenceAgent ↔ (local JSON in user_preferences/)
2. PortfolioFetcherAgent → kite_api/connector.py → Kite Connect API → returns portfolio data
3. DataAnalyzerAgent → utils/api_handler.py → Gemini AI API → enriched analysis results
4. SuggestionEngineAgent (uses analysis + preferences) → output suggestions
5. ReportGeneratorAgent → writes Markdown to reports/
c. Architectural patterns & principles:
• Agent or pipeline pattern—each agent has a single responsibility
• Layered architecture:
– Presentation/Orchestration layer: main.py, Makefile
– Configuration layer: config/settings.py, .env
– Integration layer: kite_api/connector.py, utils/api_handler.py, utils/auth.py
– Domain layer: agents/ modules
– Persistence: local file storage (JSON/MD)
• Dependency inversion: modules use abstracted connectors and handlers rather than raw HTTP calls
• Rate-limiting, retry, and error-handling are encapsulated in utils/api_handler and connector
d. Key technologies & libraries:
• Python 3.10+
• Zerodha Kite Connect Python client (via kite_api/connector.py)
• Google Gemini AI HTTP API (via utils/api_handler.py)
• dotenv or environs for config/settings.py
• Makefile for reproducible commands
• Markdown for report outputs