# Fundis

Python client for Fundis intelligence data -- events, signals, and patterns from [SentiChain](https://sentichain.com).

Fundis is the intelligence engine behind [SentiMove](https://sentimove.com). This package provides programmatic access to its structured output.

## Installation

```bash
pip install fundis
```

## Quick Start

```python
from fundis import FundisClient

client = FundisClient()

# Get classified events for an asset
events = client.get_events("BTC")
for event in events:
    print(f"[{event.type}] {event.sentiment}: {event.summary}")

# Get a directional signal with rationale
signal = client.get_signal("BTC")
if signal:
    print(f"Direction: {signal.direction}, Confidence: {signal.confidence}")
    print(f"Rationale: {signal.rationale}")
    for cat, summary in signal.categories.items():
        if summary:
            print(f"  {cat}: {summary}")

# List active tickers (fetched from the live API)
tickers = client.list_tickers()
print(tickers)

# Request a new ticker (requires API key)
client_with_key = FundisClient(api_key="sc_...")
client_with_key.request_ticker("ADA")
```

## API Reference

### `FundisClient(api_key="", base_url="https://api.fundis.ai", timeout=30.0)`

Create a client instance. Intelligence data is publicly available. An API key is only needed for ticker requests and billing-related operations on SentiChain.

### `client.get_events(ticker) -> list[Event]`

Fetch the latest classified events for a ticker. Each event contains:

| Field | Type | Description |
|-------|------|-------------|
| `timestamp` | `str` | ISO 8601 timestamp |
| `type` | `str` | Event category: `macro`, `industry`, `price`, or `asset` |
| `sentiment` | `str` | `bullish`, `bearish`, or `neutral` |
| `summary` | `str` | One-sentence event description |

### `client.get_signal(ticker) -> Signal | None`

Fetch the latest directional signal for a ticker. Returns None if no signal data exists. Otherwise returns:

| Field | Type | Description |
|-------|------|-------------|
| `direction` | `str` | `LONG`, `SHORT`, or `FLAT` |
| `confidence` | `float` | 0.0 to 1.0 |
| `rationale` | `str` | 1-2 sentence explanation of the call |
| `categories` | `dict` | One-sentence summaries for `macro`, `industry`, `price`, `asset` |
| `patterns` | `list[Pattern]` | Detected event patterns with keywords and descriptions |

### `client.list_tickers() -> list[str]`

Return the list of active ticker symbols from the live API.

### `client.request_ticker(ticker) -> bool`

Request a new ticker to be added to the pipeline. Requires an API key. Returns True if the request was submitted (pending admin approval), False if the ticker already exists.

## Requirements

- Python 3.10+

## Links

- [Fundis.ai](https://fundis.ai) -- Intelligence engine landing page
- [SentiMove](https://sentimove.com) -- 3D consumer product powered by Fundis
- [SentiChain](https://sentichain.com) -- Blockchain platform and API keys
- [GitHub](https://github.com/Yototec/fundis) -- Source code
- [PyPI](https://pypi.org/project/fundis/) -- Package registry

## License

MIT License -- see [LICENSE](LICENSE) for details.
