Metadata-Version: 2.4
Name: rr-palib
Version: 0.2.0
Summary: Python client for The Reasoning Room / Portfolio Adviser market data API
Project-URL: Homepage, https://github.com/ljohri/PALib
Project-URL: Documentation, https://github.com/ljohri/PALib
Project-URL: Repository, https://github.com/ljohri/PALib
Project-URL: API, https://api.thereasoningroom.com
Author-email: The Reasoning Room <lokesh.johri@thereasoningroom.com>
License: MIT
License-File: LICENSE
Keywords: api-client,eod,market-data,portfolio,reasoning-room
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 :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# PALib

Python client for **The Reasoning Room** Portfolio Adviser market data API.

Public repo: [github.com/ljohri/PALib](https://github.com/ljohri/PALib)

## Install

```bash
pip install rr-palib
# optional DataFrame helper
pip install rr-palib[pandas]
```

Import remains `palib`:

```python
from palib import Client
```

From a clone (editable):

```bash
git clone git@github.com:ljohri/PALib.git
cd PALib
uv pip install -e ".[dev,pandas]"
```

## Documentation and examples

| Resource | Description |
|----------|-------------|
| [`docs/index.md`](docs/index.md) | Documentation home |
| [`docs/getting-started.md`](docs/getting-started.md) | Install, env vars, `base_url` rules |
| [`docs/api/client.md`](docs/api/client.md) | Full `Client` method reference |
| [`docs/api/models.md`](docs/api/models.md) | Response models |
| [`docs/api/errors.md`](docs/api/errors.md) | Exception hierarchy |
| [`examples/`](examples/) | Runnable scripts for each API |

## Auth

Create an API key in the Portfolio Adviser web app: **Settings → Developer**. Keys look like `rr_live_…`.

```python
from palib import Client

# Explicit key
client = Client(api_key="rr_live_...")

# Or env: PALIB_API_KEY / RR_API_KEY
# Optional: PALIB_BASE_URL=http://localhost:8000
client = Client()
```

Default base URL: `https://api.thereasoningroom.com`.  
`base_url` must be an **origin only** (no `/api/...` path) — see [getting started](docs/getting-started.md).

## Usage

```python
from palib import Client

with Client(api_key="rr_live_...") as client:
    page = client.list_universe(limit=100, q="AA")
    for t in page:
        print(t.ticker, t.market_cap_b)

    hist = client.get_eod("AAPL", days=20)
    print(hist.anchor_date, hist.market_cap_b, len(hist.rows))

    macro = client.get_macro_snapshot()
    print(macro.as_of, macro.metrics["vix"].value)
```

`market_cap_b` is the **latest** universe snapshot from the API (not historical per EOD date).

## Errors

| Exception | When |
|-----------|------|
| `AuthenticationError` | Missing/invalid key, 401/403 |
| `NotFoundError` | Unknown ticker (404) |
| `ValidationError` | Bad params (422) or malformed `base_url` |
| `RateLimitError` | 429 |
| `APIError` | Other HTTP / network failures |

Details: [`docs/api/errors.md`](docs/api/errors.md).

## Tests

```bash
uv pip install -e ".[dev]"
pytest
```

## Publish to PyPI

Distribution name is **`rr-palib`** (not `palib` — that name is blocked on PyPI).  
Full monorepo runbook (uv workspace `dist/` path, TestPyPI, troubleshooting): see **`README_PALIB.md`** in the Portfolio Adviser repo.

```bash
# from portfolio_adviser monorepo root
uv build --package rr-palib
uv publish --token "$PYPI_TOKEN" dist/rr_palib-<version>*
```

Bump `version` in `pyproject.toml` and `__version__` in `src/palib/__init__.py` before each release.

## Related

- Portfolio Adviser monorepo (private): API docs live under `docs/api_readme.md`
- Live API: `https://api.thereasoningroom.com`
