Clarity

Financial Analysis Agent Built on Native Claude-skill Architecture

English (Default) | 简体中文

👉 切换到中文

Features • Quick Start • Usage • Workflow • Architecture

🌟 If you find this project helpful, please give us a Star! Your support keeps us improving!

💡 Feel free to submit Issues or PRs. We value your feedback and suggestions!

---

Introduction

Clarity is a financial analysis agent built on the native Claude-skill architecture, supporting stock analysis, holdings tracking, screening strategies, and decision dashboards. Using the Planning-with-Files pattern with multi-agent collaboration for complex financial tasks.

Key Features

• 🧠 Claude-skill Native Architecture - Following Anthropic's recommended patterns
• 🌐 Multi-Market Coverage - A-shares, HK stocks, US stocks with auto data source switching
• 📊 6 Specialized Agents - Fundamentals, technicals, news, sentiment, holdings, screening
• 🔔 Multi-Channel Push - WeChat Work, Feishu, Telegram, Email, etc.
• 🚀 REST API & Web UI - Complete interface and graphical dashboard

---

Data Sources

Clarity integrates multiple financial data sources with automatic selection based on market type:

Data Source Priority Strategy:

• A-shares: AkShare (primary) → EFinance (backup) → yFinance (fallback)
• HK stocks: yFinance
• US stocks: yFinance + Finnhub + SimFin

---

Features

---

Quick Start

Installation

git clone https://github.com/your-org/Clarity.git
cd Clarity

# Using uv (recommended)
uv sync

Configuration

Create a .env file:

# ===== Required =====
OPENAI_API_KEY=your_openai_api_key           # OpenAI API (or compatible)
FINNHUB_API_KEY=your_finnhub_api_key         # Finnhub news (free tier available)

# ===== Optional: Enhanced Search (Recommended) =====
SERPER_API_KEY=your_serper_api_key           # Google Search API
JINA_API_KEY=your_jina_api_key               # Web content extraction

# ===== Optional: Notification Channels =====
WECHAT_WEBHOOK_URL=https://qyapi.weixin.qq.com/...     # WeChat Work
FEISHU_WEBHOOK_URL=https://open.feishu.cn/...          # Feishu/Lark
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...                   # Telegram
TELEGRAM_CHAT_ID=123456789
EMAIL_SENDER=your@gmail.com                            # Email
EMAIL_PASSWORD=app_password

# ===== Optional: Qwen Model (Alibaba Qwen) =====
QWEN_API_KEY=your_dashscope_api_key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-latest
# Usage: uv run run_agent.py --model qwen analyze AAPL

---

Usage

REST API

Clarity provides a complete RESTful API interface supporting all core functionalities.

# Start API server
uv run python api.py

# Custom port and host
API_PORT=8000 API_HOST=0.0.0.0 uv run python api.py

After the API server starts, visit http://localhost:8000/docs for interactive API documentation.

API Endpoints

Usage Examples

# Analyze a stock
curl -X POST "http://localhost:8000/api/v1/analyze" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "model": "openai"}'

# Track investor holdings
curl -X POST "http://localhost:8000/api/v1/track" \
  -H "Content-Type: application/json" \
  -d '{"investor_name": "Warren Buffett"}'

# Dashboard with push notification
curl -X POST "http://localhost:8000/api/v1/dashboard" \
  -H "Content-Type: application/json" \
  -d '{"markets": ["A股", "美股"], "top_n": 10, "push": true}'

Python Client Example

import httpx
import asyncio

async def analyze_stock(ticker: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/api/v1/analyze",
            json={"ticker": ticker, "model": "openai"}
        )
    return response.json()

# Run
result = asyncio.run(analyze_stock("AAPL"))
print(result["report"])

Web UI

# activate env
source .venv/bin/activate

# Start Web interface
uv run python webui.py

# Create a public link (via Gradio Share)
uv run python webui.py --share

访问 http://localhost:7860 即可使用图形界面。

CLI 命令

# Analyze a stock
uv run python run_agent.py analyze AAPL
uv run python run_agent.py analyze NVDA --date 2025-01-15
uv run python run_agent.py --model qwen analyze AAPL

# Track investor holdings
uv run python run_agent.py track "Warren Buffett"

# Screen stocks
uv run python run_agent.py screen "high dividend yield tech stocks"

# Natural language query
uv run python run_agent.py ask "analyze Apple stock"

# 决策仪表盘
uv run python run_agent.py dashboard                           # 扫描 A股+美股
uv run python run_agent.py dashboard -m A股 港股              # 扫描指定市场
uv run python run_agent.py dashboard -n 20 -o report.md       # 推荐20只，保存到文件
uv run python run_agent.py dashboard --push                   # 扫描并推送通知
uv run python run_agent.py dashboard -p --push-to wechat      # 仅推送到企业微信
uv run python run_agent.py dashboard --interval 30            # 每隔 30 分钟运行一次
uv run python run_agent.py dashboard -i 60 --push             # 每小时运行并推送通知

Python Code

import asyncio
from clarity import FinancialAgentOrchestrator, AgentConfig, TaskType

async def main():
    orchestrator = FinancialAgentOrchestrator()

    # Analyze a stock
    result = await orchestrator.run(
        task_type=TaskType.STOCK_ANALYSIS,
        target="AAPL",
    )
    print(result["report"])

asyncio.run(main())

# Using notification service
from clarity.core import NotificationService

notification = NotificationService()
notification.send("# Test Report\nThis is a Markdown message")

---

Workflow

Planning-with-Files Pattern

The system uses three persistent files to manage long tasks, solving LLM "forgetting" problem:

Execution Flow: MasterAgent plans → WorkingAgent executes → SubAgents work → StateChecker validates → Generate report

---

Architecture

Core Agents

Directory Structure

Clarity/
├── api.py               # REST API server
├── webui.py             # Gradio Web interface
├── run_agent.py         # CLI command tool
└── clarity/
    ├── core/            # Core agents & tools
    └── dataflows/       # Data source integrations

---

Support & Contributing

This project is supported by cooragent team. Cooragent is an AI agent platform , dedicated to making everyone a commander of AI agents, which adapt, evolve, and stay aligned with users.

🌟 Support Us

If you find this project helpful:

• ⭐ Star the project - This is the best encouragement for us!
• 🐛 Submit Issues - Report bugs or suggest features
• 🔀 Submit PRs - Contributions to code and documentation are welcome
• 💬 Join the community - Share your experience with other users

📮 Contact Us

• 🌐 FeiShu: cooragent
• 📧 Feedback: Please submit via GitHub Issues

---

Star History