Metadata-Version: 2.5
Name: sentimove
Version: 2.0.0
Summary: Python client for SentiMove intelligence data - events, signals, and patterns from SentiChain.
Project-URL: Homepage, https://sentimove.com
Project-URL: Repository, https://github.com/Yototec/sentimove-sdk
Project-URL: Bug Tracker, https://github.com/Yototec/sentimove-sdk/issues
Author-email: Edward Chen <rchen@yototec.com>
License: MIT
License-File: LICENSE
Keywords: crypto,events,intelligence,patterns,sentichain,sentiment,sentimove,signals
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: requests<3.0.0,>=2.32.0
Description-Content-Type: text/markdown

# SentiMove

Python client for SentiMove intelligence reports. One report includes an asset's events and overall analysis for an inclusive 25-block period and costs one Yototec credit. The full current 15-asset overview costs 15 credits. Account, ticker and report-availability reads are free.

## Installation and account

```bash
python -m pip install git+https://github.com/Yototec/sentimove-sdk.git
```

Connect your Ethereum-compatible wallet at [Yototec Credits](https://credits.yototec.com) to initialize your permanent API key and one-time 1,000-credit grant. Reconnecting reuses the same key and balance. For additional credits, email [info@yototec.com](mailto:info@yototec.com) with your needs.

Keep the key in a secret store or environment variable. Every SDK request sends it in `Authorization: Bearer`; it never appears in the URL. Previous SentiChain credentials are retired. Website wallet sessions and SDK access use the same account balance.

## Buy one complete report

```python
import os
from sentimove import SentiMoveClient

with SentiMoveClient(api_key=os.environ["YOTOTEC_API_KEY"]) as client:
    account = client.get_account()  # Free, also available at zero credits.
    print(account.credits, account.available_credits)

    # Free discovery provides windows, revision, readiness, limitations and price.
    metadata = client.list_report_metadata(tickers=["BTC"], limit=1)
    if metadata:
        item = metadata[0]
        report = client.get_report("BTC", item["chunk_start"], item["chunk_end"])
        for event in report.events:
            print(event.timestamp, event.type, event.sentiment, event.summary)
        print(report.signal.direction, report.signal.confidence, report.signal.rationale)
        print(report.report_status, report.limitations, report.report_revision)
        print(report.billing.credits_charged, report.billing.credits_remaining)
```

`get_report()` makes one purchase. Accessing `report.events` and `report.signal` makes no further requests. Calling `get_report()` again intentionally buys the report again, even when its revision is unchanged. Compare free metadata against the last window/revision you consumed before buying new content.

A useful limited report has `report_status="limited"` and explains its limitations. Its signal may have `direction=None` and `confidence=None` while retaining substantive analysis, categories and patterns. The SDK preserves those null values. A ready signal uses `LONG`, `SHORT` or `FLAT`, with numerical confidence from 0 to 1. Unavailable reports raise an error without returning report content or charging credits.

## Full overview

```python
snapshot = client.get_latest_snapshot()
print(snapshot.chunk_start, snapshot.chunk_end)
print(snapshot.billing.credits_charged, snapshot.billing.credits_remaining)
for report in snapshot.assets:
    print(report.ticker, report.signal.rationale)
```

Run this while the client is open. A snapshot includes all active assets in one coherent period, including useful limited reports. Billing is on `snapshot.billing`; individual snapshot assets have `billing=None`. An unavailable asset or insufficient balance rejects the entire purchase without content or debit. For example, a 15-asset purchase with 14 credits leaves all 14 credits available. Use free metadata to identify a smaller available report to request individually.

## Retries and errors

Each `get_report()` or `get_latest_snapshot()` call creates one UUID in `Idempotency-Key`. Connection failures and timeouts retry at most twice by default, reusing that UUID and the same request. HTTP errors are returned immediately. A later intentional purchase receives a new UUID.

You can explicitly supply `operation_id` to resume the same purchase after an uncertain transport outcome. Keep its exact ticker/window or snapshot request. Reusing that ID for different resources is a conflict. Latest-snapshot retries remain bound to the original operation's frozen period, even if a newer period becomes available.

```python
from uuid import uuid4
from sentimove import APIError, AuthenticationError, InsufficientCreditsError

operation_id = str(uuid4())  # Persist alongside the exact requested resource.
try:
    report = client.get_report("BTC", 130175, 130199, operation_id=operation_id)
except InsufficientCreditsError as exc:
    print(exc.required_credits, exc.available_credits)  # Integers; no purchase occurred.
except AuthenticationError:
    print("Check your Yototec API key.")
except APIError as exc:
    # Retain this ID for recovery; do not automatically start another purchase.
    print(exc.status_code, exc.code, exc.operation_id)
```

Successful paid results expose `Billing(credits_charged: int, credits_remaining: int, operation_id: str)` parsed from `X-Yototec-Credits-Charged`, `X-Yototec-Credits-Remaining` and `X-Yototec-Operation-Id`. Invalid report or billing responses raise `APIError(code="invalid_response")`; validated billing is retained on `exc.billing` when available. Transport errors use `code="transport_error"`. Keys and raw transport exception messages are excluded from SDK errors.

## API reference

`SentiMoveClient(api_key, base_url="https://api.sentimove.com", timeout=30.0, transport_retries=2)` supports context-manager use and `close()`. Timeouts are positive seconds; `transport_retries` is an integer from 0 to 5. Redirects are rejected to keep credentials at the configured endpoint.

| Method | HTTP request | Result / price |
| --- | --- | --- |
| `get_report(ticker, chunk_start, chunk_end, *, operation_id=None)` | `GET /agent/report?ticker=BTC&chunk_start=130175&chunk_end=130199` | `Report`; 1 credit |
| `get_latest_snapshot(*, operation_id=None)` | `GET /agent/latest_snapshot` | `Snapshot`; 1 credit per asset |
| `list_report_metadata(tickers=None, *, before_chunk=None, limit=100)` | `GET /agent/report_metadata?tickers=BTC,ETH&before_chunk=130200&limit=100` | List of metadata dictionaries; free |
| `get_account()` | `GET /yototec/account` | `Account(wallet, credits, available_credits)`; free |
| `list_tickers()` | `GET /agent/tickers` | List of active identifiers; free |

Ticker symbols are normalized to uppercase. Report windows must begin at a multiple of 25 and end 24 blocks later. Metadata accepts 1 to 100 rows; omit `tickers` for all active assets. `before_chunk` filters prior windows. Metadata never includes event text, signals or embeddings.

`Report` contains ticker, chunk boundaries, status, limitations, opaque revision, `events`, `signal` and optional billing. Each event retains timestamp, type, sentiment and summary. `Signal` retains direction, confidence, rationale, category summaries and `Pattern` entries with keywords, event indices and descriptions.

## Updating existing integrations

This release replaces public component reads and old credentials. Replace `get_events(ticker)` and `get_signal(ticker)` with a single `get_report()` followed by local `report.events` and `report.signal` access. The separate component methods, ticker-request method and former package aliases are removed. Enroll a Yototec account and configure its API key before using the client.

The service uses `https://api.sentimove.com`; configured API host aliases enforce the same access policy. The SDK does not provide live asset-header prices.

Verify locally without production accounts or charges:

```bash
python -m unittest discover -s tests -v
python -m build
```

The contract tests use a local HTTP server and isolated test-only credentials and balances.

## Links

- [SentiMove](https://sentimove.com)
- [Yototec Credits](https://credits.yototec.com)
- [Source](https://github.com/Yototec/sentimove-sdk)
- [Package registry](https://pypi.org/project/sentimove/)

MIT License. See [LICENSE](LICENSE).
