Metadata-Version: 2.4
Name: matrx-legal
Version: 0.1.5
Summary: Legal data integrations (CourtListener, citations, case law) for the Matrx ecosystem
Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
Project-URL: Issues, https://github.com/AI-Matrix-Engine/aidream-current/issues
Author-email: Matrx <admin@aimatrx.com>
Maintainer-email: Matrx <admin@aimatrx.com>
License: MIT
Keywords: case-law,courtlistener,legal,matrx,pacer,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: matrx-utils>=1.0.20
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Provides-Extra: connect
Requires-Dist: matrx-connect>=0.1.1; extra == 'connect'
Provides-Extra: orm
Requires-Dist: matrx-orm>=3.0.32; extra == 'orm'
Description-Content-Type: text/markdown

# matrx-legal

Legal data integrations for the Matrx ecosystem. Standalone-installable; first-class inside aidream.

**Initial provider:** CourtListener (REST API v4, bulk S3 dumps, webhooks).
Designed to host additional sources (Westlaw, Lexis, Justia, CAP, Caselaw Access Project) behind a uniform interface.

## What it does

- Async client for CourtListener REST API v4 with token-bucket throttling, cursor pagination, retry, and 429/`Retry-After` handling.
- Pydantic models for every public response shape.
- Optional ORM persistence (matrx-orm) for cached opinions, dockets, courts, citations.
- Optional bulk ingest from CourtListener's free quarterly S3 dumps via Postgres `COPY`.
- Optional RAG indexing of opinion full-text (host injects the embedder).
- Optional FastAPI streaming endpoints (host wires them up).
- AI tool callables ready to register with `matrx-ai`'s tools registry.

## Quick start

```python
import asyncio
from matrx_legal.courtlistener import CourtListenerClient

async def main():
    async with CourtListenerClient() as client:
        async for hit in client.search(q="miranda v arizona", type="o", page_size=20):
            print(hit.case_name, hit.absolute_url)

asyncio.run(main())
```

Set `COURTLISTENER_API_TOKEN` in your environment.

## Host integration

```python
import matrx_legal
from my_app.settings import settings
from my_app.db import LegalOpinion, LegalDocket  # subclassed from matrx_legal.orm

matrx_legal.configure(
    settings=settings,
    db_models={"LegalOpinion": LegalOpinion, "LegalDocket": LegalDocket, ...},
    file_handler_class=FileManager,
    embedder=my_embedder,
)
```

## Standalone testing

```bash
uv run pytest packages/matrx-legal/tests
```

Tests must pass with only `matrx-utils` installed.
