<div align="center">
  <img src="images/title_logo.jpg" alt="OpenKite Logo" width="600"/>
</div>

---

## Overview

OpenKite is an AI-powered agentic trading assistant that combines real-time market access, fundamental analysis, and web intelligence into a single intelligent workflow. Built on the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), it autonomously selects and orchestrates tools to answer complex trading and investment queries — without you having to switch between multiple platforms.

## Features

| | Feature | Description |
|---|---|---|
| 🤖 | **Agentic Reasoning** | Dynamically decides which tools to invoke based on user intent; minimizes unnecessary calls while maximizing insight |
| 📈 | **Zerodha Kite Integration** | Fetch portfolio, positions, and holdings; place orders (including GTT); access real-time market data via the official Kite MCP server |
| 🌐 | **Web Intelligence via Firecrawl** | Pull the latest news, trends, and external signals to enhance decision-making with real-world context |
| 📊 | **Fundamental Analysis via Screener.in** | Retrieve company financials, key ratios, and quarterly trends for long-term investment research via a custom-built CLI tool — [screenercli](https://github.com/mayur1064/screenercli) |

## Architecture

<div align="center">
  <img src="images/architecture.jpg" alt="OpenKite Architecture" width="820"/>
</div>

The agent orchestrator sits between the OpenAI Agents SDK and three tool groups:

- **Remote MCP** — Zerodha Kite MCP server for live trading operations
- **Local MCP** — Firecrawl MCP server for web crawl and search
- **Custom CLI Tools** — Screener.in CLI for fundamental data lookups

## Installation

```bash
pip install openkite
```

For local development:

```bash
pip install -e .[dev]
```

> **Prerequisite:** Node.js (`npx`) is required to run the Firecrawl MCP server.

## Configuration

Create a `.env` file in your working directory (or supply it via `--env-file`):

```dotenv
OPENAI_API_KEY=sk-...
FIRECRAWL_API_KEY=fc-...
OPENKITE_MODEL=gpt-4o
ZERODHA_MCP_SSE_URL=https://mcp.kite.trade/sse
OPENKITE_DB_PATH=~/.openkite/chat_history.db
OPENKITE_HOST=127.0.0.1
OPENKITE_PORT=7860
OPENKITE_SHARE=false
```

> Keep `.env` out of source control — add it to `.gitignore`.

| Variable | Description |
|---|---|
| `OPENAI_API_KEY` | Your OpenAI API key |
| `FIRECRAWL_API_KEY` | Your Firecrawl API key |
| `OPENKITE_MODEL` | OpenAI model to use (e.g. `gpt-4o`) |
| `ZERODHA_MCP_SSE_URL` | Zerodha Kite MCP SSE endpoint |
| `OPENKITE_DB_PATH` | Path for persisting chat history |
| `OPENKITE_HOST` | Host for the Gradio UI server |
| `OPENKITE_PORT` | Port for the Gradio UI server |
| `OPENKITE_SHARE` | Set `true` to create a public Gradio share link |

## Usage

Launch the chat UI:

```bash
openkite chat
```

Validate your configuration:

```bash
openkite check
```

Pass custom runtime options:

```bash
openkite chat --env-file .env --host 0.0.0.0 --port 7860
```

## Example Prompts

Try these in the chat UI to exercise Kite MCP, Firecrawl, and Screener together:

**Portfolio & Positions**
- `Show my current holdings with live prices, day change, unrealised P&L, and portfolio weights.`
- `List my open positions and pending orders, then flag anything that needs attention today.`
- `Review my top holdings by value using live Kite data, Screener fundamentals, and recent news, then highlight key risks and opportunities without placing orders.`

**Fundamental Analysis**
- `Compare TCS and Infosys : valuation, growth, margins, ROCE, and the latest quarterly trend.`
- `Show the last 4 quarters for HDFCBANK  and tell me whether revenue, profit, and return ratios are improving or weakening.`

**Market Intelligence**
- `Use recent web coverage to summarize the most important Reliance Industries news from the last 7 days and explain the likely market impact.`
- `For NSE:INFY, combine live Kite price action, fundamentals, and recent web news into a short trading and investment brief.`

## Screenshots

<div align="center">
  <img src="images/sample_image1.jpg" alt="OpenKite Chat Interface" width="780"/>
  <p><em>Chat interface with example prompt suggestions</em></p>
</div>

<div align="center">
  <img src="images/sample_image2.jpg" alt="OpenKite Portfolio Analysis" width="780"/>
  <p><em>AI-generated portfolio analysis with sell recommendations</em></p>
</div>

<div align="center">
  <img src="images/sample_image3.jpg" alt="OpenKite Tool Calls" width="780"/>
  <p><em>Live agent tool-call trace during a Nifty 50 scan</em></p>
</div>
