Metadata-Version: 2.4
Name: openfinclaw
Version: 0.2.7
Summary: OpenFinClaw SDK — Python client & CLI for the DeepAgent API
Requires-Python: >=3.10
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.28
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Description-Content-Type: text/markdown

# OpenFinClaw SDK

AI-powered financial analysis agent. Ask questions in natural language, get professional research reports.

## Install

```bash
# Recommended (uv)
uv tool install "openfinclaw[cli]"

# Or pip (Python 3.10+, quote the brackets in zsh)
pip install "openfinclaw[cli]"
```

**Update to latest version:**
```bash
uv cache clean openfinclaw && uv tool install --force "openfinclaw[cli]"
```

> Don't have uv? Install it first: `curl -LsSf https://astral.sh/uv/install.sh | sh`

## Quick Start

### CLI (Interactive Terminal)

```bash
openfinclaw-cli
```

Or ask a single question:
```bash
openfinclaw-cli "分析宁德时代的投资价值"
```

### Python SDK (Programmatic)

```bash
pip install openfinclaw
```

```python
from openfinclaw import OpenFinClawClient

client = OpenFinClawClient()

# Create a conversation thread
thread = client.create_thread()

# Stream the response
for event in client.stream(thread.id, "分析宁德时代的投资价值"):
    if event.type == "TEXT_DELTA":
        print(event.text, end="", flush=True)
```

## Features

- **Multi-turn conversations** — context is preserved across messages
- **Real-time streaming** — see the response as it's generated (SSE)
- **58+ financial skills** — stock analysis, macro, crypto, derivatives, backtesting, and more
- **Multi-agent architecture** — specialized agents (analyst, researcher, risk manager, strategist) collaborate on your query

## CLI Commands

| Command | Description |
|---------|-------------|
| `/new` | Create a new conversation thread |
| `/threads` | List all threads |
| `/history` | Show message history |
| `/runs` | Show run history |
| `/cancel` | Cancel the active run |
| `/help` | Show available commands |
| `/quit` | Exit |

## SDK API Reference

```python
client = OpenFinClawClient(api_key="your-key", base_url="https://api.openfinclaw.ai/agent")

# Thread management
thread = client.create_thread(title="My Analysis")
threads = client.list_threads()

# Messages & Runs
messages = client.list_messages(thread.id)
runs = client.list_runs(thread.id)
client.cancel_run(thread.id, run.id)

# Streaming (returns Iterator[Event])
for event in client.stream(thread.id, "your question"):
    match event.type:
        case "TEXT_DELTA":    print(event.text)       # response text chunk
        case "TOOL_START":    print(event.tool_name)   # tool being called
        case "TOOL_DONE":     ...                      # tool finished
        case "AGENT_HANDOFF": print(event.agent_name)  # agent delegation
        case "RUN_FINISHED":  ...                      # done
        case "ERROR":         print(event.error)       # error occurred
```

## Error Handling

```python
from openfinclaw import OpenFinClawClient, RateLimitError, AuthError

client = OpenFinClawClient()
try:
    for event in client.stream(thread.id, "question"):
        ...
except RateLimitError:
    print("Daily limit reached (30/day)")
except AuthError:
    print("Invalid API key")
```

## Example Use Cases

**A-share**
```
You: 300750 宁德时代深度分析 — 固态电池进展和估值
You: 今天A股有哪些热门板块和涨停股？龙虎榜有什么异动？
You: 人形机器人概念还能追吗？当前处于炒作周期的什么阶段？
You: 用双均线策略回测沪深300，过去一年表现如何？
```

**US Stock**
```
You: NVDA 英伟达 Q4 财报分析，AI 算力需求是否见顶？
You: 对比 TSLA vs BYD，谁的估值更有吸引力？
You: 美联储降息周期下，哪些美股板块最受益？
```

**Crypto & Macro**
```
You: BTC 当前处于减半周期的什么阶段？山寨季来了吗？
You: 当前中国宏观经济形势如何？CPI/PPI/PMI 趋势
You: 帮我构建一个攻守兼备的A股ETF组合
```

## Limits

- **30 requests/day** per API key
- Beta access expires on the date specified by your key

## Links

- Issues & Feedback: [GitHub Issues](https://github.com/cryptoSUN2049/findoo-deepagent-openai-agent/issues)
