tzzb 0.2.0__tar.gz

tzzb-0.2.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: tzzb
+Version: 0.2.0
+Summary: Python SDK, CLI and MCP server for Tonghuashun Investment Ledger (同花顺投资账本)
+Author: brwchen
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websocket-client>=1.8.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+
+# tzzb
+
+Python SDK, CLI tool, and Model Context Protocol (MCP) server for **Tonghuashun Investment Ledger (同花顺投资账本)**.
+
+Provides programmatic access to multi-broker positions, intraday trades & T+0 arbitrage breakdown, historical transaction ledger, asset curves, monthly profit calendars, individual stock profit contribution rankings, and time-share curves with zero token overhead for Python apps and seamless AI Agent integration.
+
+---
+
+## Key Features
+
+- **Direct Python SDK (`TzzbClient`)**: Native Python calls for automated financial pipelines, SQLite sync, and quantitative tracking returning raw JSON-serializable dictionaries.
+- **Rich Terminal CLI**: Beautiful, high-density terminal tables with TrueColor RGB opacity control and compact financial layouts.
+- **Intraday T+0 (做T) Arbitrage Analysis**: Automatically detects same-day buy and sell executions per stock, computes hedged T-volume, buy/sell average prices, price spreads, net T-profits, and remaining position changes.
+- **Monthly Profit Calendar & Win Rates**: Computes daily profit & loss, yield %, trading days, winning days, and monthly win rate summary.
+- **Stock Profit Contribution Leaderboard**: Ranks winning and losing stocks by year, holding period, month, or intraday.
+- **Intraday Time-Share Curve**: Monitors minute-by-minute profit curves and key time checkpoints (e.g. 09:30, 10:30, 11:30, 14:00, 15:00).
+- **Multi-Account Auto Aggregation**: Automatically aggregates multiple securities brokers, manual accounts, and margin (融资融券) accounts across all data endpoints.
+- **Global Configuration**: Configurable color display and terminal opacity (`~/.tzzb/config.json`).
+- **Model Context Protocol (MCP)**: Native FastMCP server for Claude Desktop, Copilot, and custom AI agents.
+- **Chrome CDP Bridge**: Connects to isolated Chrome instance over DevTools Protocol, automatically attaching dynamic `hexin-v` anti-bot headers with persistent session cookies (`~/.tzzb_cookies.json`).
+
+---
+
+## Installation
+
+```bash
+pip install tzzb
+```
+
+Or install from source in editable mode:
+
+```bash
+git clone https://github.com/brwchen/tzzb.git
+cd tzzb
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Python SDK
+
+```python
+from tzzb import TzzbClient
+
+client = TzzbClient()
+
+# Check authentication status
+status = client.get_login_status()
+print(f"Logged in: {status.logged_in}, User ID: {status.userid}")
+
+# Asset & profit overview
+overview = client.get_overview()
+
+# Multi-account positions
+positions = client.get_positions()
+
+# Today's executions & T+0 trading flows
+today_trades = client.get_today_trades()
+
+# Monthly profit calendar (e.g. '2026-10')
+calendar = client.get_profit_calendar("2026-10")
+
+# Profit contribution rankings (rank_type: 'year' | 'hold' | 'month' | 'today')
+rankings = client.get_rankings(rank_type="year")
+
+# Intraday minute time-share profit checkpoints
+time_share = client.get_time_share()
+```
+
+### 2. Command Line Interface (CLI)
+
+```bash
+# Authentication & Status
+tzzb status
+tzzb login
+tzzb logout
+
+# Overview & Accounts
+tzzb overview                    # alias: tzzb ov
+tzzb accounts                    # alias: tzzb acc
+
+# Positions
+tzzb positions                   # alias: tzzb pos (compact view)
+tzzb positions -d                # detailed view with costs, market values, profit ratios
+
+# Intraday Trades & T+0 Arbitrage
+tzzb t                           # alias: tzzb today-trades, tzzb trades, tzzb t0
+tzzb t 600519                    # filter trades and T-arbitrage by stock code
+
+# Profit Calendar & Win Rates
+tzzb calendar                    # alias: tzzb cal (current month)
+tzzb calendar 2026-09            # specify historical month
+
+# Profit Contribution Rankings
+tzzb rank                        # alias: tzzb ranking (annual rankings)
+tzzb rank --by hold              # ranking by holding period
+tzzb rank --by month             # ranking by monthly profit
+
+# Intraday Time-Share Curve
+tzzb timeshare                   # alias: tzzb ts
+
+# Global Configuration
+tzzb config                      # view current config
+tzzb config set color true       # enable/disable colors
+tzzb config set opacity 0.8      # set terminal opacity (0.0 - 1.0)
+tzzb config reset                # reset to defaults
+```
+
+### 3. Model Context Protocol (MCP)
+
+Add `tzzb-mcp` to your MCP configuration (e.g. `claude_desktop_config.json` or Copilot MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "tzzb": {
+      "command": "tzzb-mcp"
+    }
+  }
+}
+```
+
+Exposed MCP Tools:
+- `tzzb_get_status`: Get current authentication and user status.
+- `tzzb_login` / `tzzb_logout`: QR login or session logout.
+- `tzzb_get_overview`: Total asset, market value, cash balance, and profits.
+- `tzzb_get_accounts`: List all bound brokerage and manual accounts.
+- `tzzb_get_positions`: Real-time stock holdings, shares, costs, and profit percentages.
+- `tzzb_get_today_trades`: Intraday order executions and T+0 arbitrage data.
+- `tzzb_get_profit_calendar`: Monthly daily PnL and win rate statistics.
+- `tzzb_get_rankings`: Stock profit contribution rankings.
+- `tzzb_get_time_share`: Intraday minute profit checkpoints.
+
+---
+
+## Configuration
+
+Configuration file is automatically created at `~/.tzzb/config.json`:
+
+```json
+{
+  "color": true,
+  "opacity": 1.0
+}
+```
+
+---
+
+## License
+
+MIT
+

tzzb-0.2.0/README.md

@@ -0,0 +1,154 @@
+# tzzb
+
+Python SDK, CLI tool, and Model Context Protocol (MCP) server for **Tonghuashun Investment Ledger (同花顺投资账本)**.
+
+Provides programmatic access to multi-broker positions, intraday trades & T+0 arbitrage breakdown, historical transaction ledger, asset curves, monthly profit calendars, individual stock profit contribution rankings, and time-share curves with zero token overhead for Python apps and seamless AI Agent integration.
+
+---
+
+## Key Features
+
+- **Direct Python SDK (`TzzbClient`)**: Native Python calls for automated financial pipelines, SQLite sync, and quantitative tracking returning raw JSON-serializable dictionaries.
+- **Rich Terminal CLI**: Beautiful, high-density terminal tables with TrueColor RGB opacity control and compact financial layouts.
+- **Intraday T+0 (做T) Arbitrage Analysis**: Automatically detects same-day buy and sell executions per stock, computes hedged T-volume, buy/sell average prices, price spreads, net T-profits, and remaining position changes.
+- **Monthly Profit Calendar & Win Rates**: Computes daily profit & loss, yield %, trading days, winning days, and monthly win rate summary.
+- **Stock Profit Contribution Leaderboard**: Ranks winning and losing stocks by year, holding period, month, or intraday.
+- **Intraday Time-Share Curve**: Monitors minute-by-minute profit curves and key time checkpoints (e.g. 09:30, 10:30, 11:30, 14:00, 15:00).
+- **Multi-Account Auto Aggregation**: Automatically aggregates multiple securities brokers, manual accounts, and margin (融资融券) accounts across all data endpoints.
+- **Global Configuration**: Configurable color display and terminal opacity (`~/.tzzb/config.json`).
+- **Model Context Protocol (MCP)**: Native FastMCP server for Claude Desktop, Copilot, and custom AI agents.
+- **Chrome CDP Bridge**: Connects to isolated Chrome instance over DevTools Protocol, automatically attaching dynamic `hexin-v` anti-bot headers with persistent session cookies (`~/.tzzb_cookies.json`).
+
+---
+
+## Installation
+
+```bash
+pip install tzzb
+```
+
+Or install from source in editable mode:
+
+```bash
+git clone https://github.com/brwchen/tzzb.git
+cd tzzb
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Python SDK
+
+```python
+from tzzb import TzzbClient
+
+client = TzzbClient()
+
+# Check authentication status
+status = client.get_login_status()
+print(f"Logged in: {status.logged_in}, User ID: {status.userid}")
+
+# Asset & profit overview
+overview = client.get_overview()
+
+# Multi-account positions
+positions = client.get_positions()
+
+# Today's executions & T+0 trading flows
+today_trades = client.get_today_trades()
+
+# Monthly profit calendar (e.g. '2026-10')
+calendar = client.get_profit_calendar("2026-10")
+
+# Profit contribution rankings (rank_type: 'year' | 'hold' | 'month' | 'today')
+rankings = client.get_rankings(rank_type="year")
+
+# Intraday minute time-share profit checkpoints
+time_share = client.get_time_share()
+```
+
+### 2. Command Line Interface (CLI)
+
+```bash
+# Authentication & Status
+tzzb status
+tzzb login
+tzzb logout
+
+# Overview & Accounts
+tzzb overview                    # alias: tzzb ov
+tzzb accounts                    # alias: tzzb acc
+
+# Positions
+tzzb positions                   # alias: tzzb pos (compact view)
+tzzb positions -d                # detailed view with costs, market values, profit ratios
+
+# Intraday Trades & T+0 Arbitrage
+tzzb t                           # alias: tzzb today-trades, tzzb trades, tzzb t0
+tzzb t 600519                    # filter trades and T-arbitrage by stock code
+
+# Profit Calendar & Win Rates
+tzzb calendar                    # alias: tzzb cal (current month)
+tzzb calendar 2026-09            # specify historical month
+
+# Profit Contribution Rankings
+tzzb rank                        # alias: tzzb ranking (annual rankings)
+tzzb rank --by hold              # ranking by holding period
+tzzb rank --by month             # ranking by monthly profit
+
+# Intraday Time-Share Curve
+tzzb timeshare                   # alias: tzzb ts
+
+# Global Configuration
+tzzb config                      # view current config
+tzzb config set color true       # enable/disable colors
+tzzb config set opacity 0.8      # set terminal opacity (0.0 - 1.0)
+tzzb config reset                # reset to defaults
+```
+
+### 3. Model Context Protocol (MCP)
+
+Add `tzzb-mcp` to your MCP configuration (e.g. `claude_desktop_config.json` or Copilot MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "tzzb": {
+      "command": "tzzb-mcp"
+    }
+  }
+}
+```
+
+Exposed MCP Tools:
+- `tzzb_get_status`: Get current authentication and user status.
+- `tzzb_login` / `tzzb_logout`: QR login or session logout.
+- `tzzb_get_overview`: Total asset, market value, cash balance, and profits.
+- `tzzb_get_accounts`: List all bound brokerage and manual accounts.
+- `tzzb_get_positions`: Real-time stock holdings, shares, costs, and profit percentages.
+- `tzzb_get_today_trades`: Intraday order executions and T+0 arbitrage data.
+- `tzzb_get_profit_calendar`: Monthly daily PnL and win rate statistics.
+- `tzzb_get_rankings`: Stock profit contribution rankings.
+- `tzzb_get_time_share`: Intraday minute profit checkpoints.
+
+---
+
+## Configuration
+
+Configuration file is automatically created at `~/.tzzb/config.json`:
+
+```json
+{
+  "color": true,
+  "opacity": 1.0
+}
+```
+
+---
+
+## License
+
+MIT
+

tzzb-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tzzb"
+version = "0.2.0"
+description = "Python SDK, CLI and MCP server for Tonghuashun Investment Ledger (同花顺投资账本)"
+readme = "README.md"
+authors = [
+    { name = "brwchen" }
+]
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "websocket-client>=1.8.0",
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+tzzb = "tzzb.cli:main"
+tzzb-mcp = "tzzb.mcp:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tzzb-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tzzb-0.2.0/src/tzzb/__init__.py

@@ -0,0 +1,18 @@
+"""tzzb — Python SDK, CLI, and MCP Server for Tonghuashun Investment Ledger (同花顺投资账本)."""
+
+from .client import TzzbClient, TzzbError
+from .config import TzzbConfig, config
+from .models import Account, AssetTrendPoint, LoginStatus, Position, TradeRecord
+
+__all__ = [
+    "TzzbClient",
+    "TzzbError",
+    "TzzbConfig",
+    "config",
+    "Account",
+    "AssetTrendPoint",
+    "LoginStatus",
+    "Position",
+    "TradeRecord",
+]
+__version__ = "0.1.0"