Metadata-Version: 2.4
Name: triangula-sdk
Version: 0.1.0
Summary: Official Python client for the Triangula archetype API (16 face archetypes, compatibility matrix).
Author: Sergius G.
License: MIT
Project-URL: Homepage, https://triangula.app
Project-URL: Releases, https://pypi.org/project/triangula/
Keywords: triangula,archetypes,personality,face-reading,compatibility,psychometrics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# triangula

Official Python client for the **[Triangula](https://triangula.app)** archetype API —
16 face archetypes scored from facial geometry and 12 questionnaire answers, plus the
compatibility matrix (synergy / resonance / tension).

> For entertainment and self-reflection only. Not a diagnostic instrument.

## Install

```bash
pip install triangula-sdk
```

Python 3.8+, **zero dependencies** (stdlib `urllib`).

## Quick start

```python
from triangula import Triangula

client = Triangula(api_key="tk_...")

reading = client.reading(
    answers=[5, 4, 5, 1, 2, 1, 5, 3, 1, 4, 2, 1],  # exactly 12 values, each 1..5
    face=None,                                       # optional derived face metrics
)

print(reading["archetype"])       # {'code': 'AA-bc', 'name': 'Pure Leader'}
print(reading["compatibility"])   # {'synergy': [...], 'resonance': [...], 'tension': [...]}
```

## API

### `Triangula(api_key=None, base_url="https://triangula.app", timeout=30.0)`

### `client.reading(answers, face=None)`

`answers` — exactly 12 numbers in the 1..5 range (validated client-side before any request).
Returns the reading dict: `archetype`, `scores`, `confidence`, `narrative`, `compatibility`,
`disclaimer`, `timestamp`.

### `client.archetypes()`

All 16 archetypes with names and metadata.

### `client.health()`

Service health (`{"ok": True, "archetypes_loaded": 16}`).

### `client.last_rate_limit`

`{"limit", "remaining", "reset"}` from the most recent response.

## Errors

```python
from triangula import TriangulaError

try:
    client.reading(answers)
except TriangulaError as e:
    print(e.status, e.code)   # 401 invalid_api_key · 429 quota_exceeded · 429 rate_limited
```

## Limits

- Per-key quota: 100 requests per UTC day (configurable per key by Triangula).
- Keyless calls (the website itself) are limited per IP and intended for first-party use.
- Do not send photos: Triangula is built so images never leave the user's device. This client
  accepts only derived face metrics and questionnaire answers.

## Links

- Product: https://triangula.app
- Method & FAQ: https://triangula.app/science
- The 16 archetypes: https://triangula.app/16-face-archetypes

## License

MIT © Sergius G.
