Metadata-Version: 2.4
Name: north7
Version: 0.1.1
Summary: Python SDK for the NORTH7 Financial Intelligence API
Author-email: NORTH7 GmbH <dev@north7.ai>
License-Expression: MIT
Project-URL: Homepage, https://north7.ai
Project-URL: Documentation, https://north7.ai/developer
Project-URL: Repository, https://github.com/a10102010/north7-agent-api
Project-URL: Issues, https://github.com/a10102010/north7-agent-api/issues
Keywords: finance,trading,api,signals,risk,intelligence,north7
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# NORTH7 Python SDK

Official Python SDK for the [NORTH7 Financial Intelligence API](https://north7.ai).

Real-time risk scoring, market regime detection, trading signals, stock analysis,
commodity intelligence, and geopolitical briefings -- all from one API.

## Installation

```bash
pip install north7
```

With LangChain support:

```bash
pip install north7[langchain]
```

## Quick Start

```python
from north7 import North7Client

# Free endpoints -- no API key required
client = North7Client()

risk = client.risk()
print(f"Risk: {risk.value}/100 - {risk.status}")

regime = client.regime()
print(f"Regime: {regime.regime}, VIX: {regime.vix_value}")
```

## Authentication

Get a free API key:

```python
info = North7Client.register(email="you@example.com", name="Your Name")
print(info.api_key)  # n7_live_...
```

Or sign up at [north7.ai/developer](https://north7.ai/developer).

Use the key:

```python
client = North7Client(api_key="n7_live_xxx")

# Or set the environment variable
# export NORTH7_API_KEY=n7_live_xxx
client = North7Client()  # picks up from env
```

## Endpoints

### Free (no key needed)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `client.risk()` | GET /v1/risk | Global risk index (0-100) |
| `client.regime()` | GET /v1/regime | Market regime (BULL/BEAR/NEUTRAL) |
| `client.health()` | GET /v1/health | API health check |

### Authenticated (costs credits)

| Method | Credits | Description |
|--------|---------|-------------|
| `client.signals()` | 1 | Latest trading signals |
| `client.alpha()` | 2 | Alpha stock picks |
| `client.prices(["AAPL", "MSFT"])` | 1 | Current prices |
| `client.price_history("AAPL")` | 1 | OHLCV price history |
| `client.analysis("AAPL")` | 5 | Full stock analysis |
| `client.sector_radar()` | 2 | Sector rotation radar |
| `client.commodities()` | 2 | Commodity signals |
| `client.intraday()` | 2 | Intraday scanner |
| `client.briefing()` | 10 | Geopolitical briefing |
| `client.portfolio()` | 10 | Model portfolio |

## Examples

### Trading Signals

```python
client = North7Client(api_key="n7_live_xxx")

signals = client.signals()
for s in signals:
    print(f"{s.symbol}: {s.direction} ({s.confidence})")
```

### Stock Analysis

```python
report = client.analysis("NVDA")
print(f"{report.symbol}: {report.rating} ({report.score}/100)")
print(report.summary)
```

### Sector Rotation

```python
sectors = client.sector_radar()
for sector in sectors:
    print(f"{sector.sector}: {sector.score} ({sector.trend})")
```

### Commodity Signals

```python
commodities = client.commodities()
for c in commodities:
    print(f"{c.name} ({c.symbol}): {c.direction}")
```

### Geopolitical Briefing

```python
brief = client.briefing()
print(brief.summary)
for event in brief.events:
    print(f"  - {event}")
```

## Async Support

```python
import asyncio
from north7 import AsyncNorth7Client

async def main():
    async with AsyncNorth7Client(api_key="n7_live_xxx") as client:
        risk = await client.risk()
        print(f"Risk: {risk.value}/100")

        signals = await client.signals()
        for s in signals:
            print(f"{s.symbol}: {s.direction}")

asyncio.run(main())
```

## LangChain Integration

Use NORTH7 as tools in a LangChain agent:

```python
from north7 import North7Client

client = North7Client(api_key="n7_live_xxx")
tools = client.get_langchain_tools()

# Use with any LangChain agent
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
result = executor.invoke({"input": "What is the current market risk?"})
```

## Error Handling

```python
from north7 import North7Client, AuthenticationError, RateLimitError

client = North7Client(api_key="invalid")

try:
    signals = client.signals()
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except InsufficientCreditsError:
    print("Not enough credits")
```

## Response Types

All methods return typed dataclasses, not raw dicts:

```python
risk = client.risk()
risk.value      # int: 0-100
risk.status     # str: "LOW", "MODERATE", "ELEVATED", "HIGH", "EXTREME"
risk.crises     # List[Crisis]
risk.regions    # List[RegionRisk]
```

## License

MIT -- see [LICENSE](LICENSE).
