Metadata-Version: 2.4
Name: descrybe-legal-engine
Version: 0.1.0
Summary: Python client and CLI for connecting apps and agents to Descrybe Legal Engine with per-user OAuth.
Project-URL: Homepage, https://descrybe.com
Project-URL: Documentation, https://descrybe.com/docs/legal-engine-sdk
Project-URL: Terms, https://descrybe.com/terms
Project-URL: Repository, https://github.com/descrybe-com/descrybe-legal-engine-python
Author: Descrybe
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: descrybe,legal ai,legal research,mcp,oauth
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Provides-Extra: secure-storage
Requires-Dist: keyring>=25.0; extra == 'secure-storage'
Provides-Extra: test
Description-Content-Type: text/markdown

# Descrybe Legal Engine Python

[![CI](https://github.com/descrybe-com/descrybe-legal-engine-python/actions/workflows/ci.yml/badge.svg)](https://github.com/descrybe-com/descrybe-legal-engine-python/actions/workflows/ci.yml)

Python client and CLI for connecting apps and agents to Descrybe Legal Engine
with per-user OAuth.

This package is for developers building local research agents, firm tools, and
AI workflows that need authenticated access to Descrybe Legal Engine without
turning one person's account into a shared team credential.

## Status

This repository is in an early scaffold state. The first slice includes package
metadata, a CLI, token-storage primitives, OAuth request helpers, local
loopback login, refresh-token rotation, a small MCP client, and agent
instructions.

## Install

```bash
pip install descrybe-legal-engine
```

For local development from this repository:

```bash
python -m pip install -e .
```

## Core Rule

Each human user should connect their own Descrybe account through OAuth.

For a 20-person firm app, the intended pattern is 20 app users, 20 Descrybe
OAuth connections, and Descrybe calls attributed to the actual user. Do not use
one user's OAuth token, refresh token, password, or subscription to serve other
people unless Descrybe has separately approved that access model.

## CLI

Write agent instructions into a project:

```bash
dle init-agent-instructions
```

This creates `DESCRYBE_LEGAL_ENGINE.md`, a paste-this-into-your-coding-LLM
instruction sheet that tells the assistant how to use the SDK without creating
one shared Descrybe credential for a team.

Inspect local SDK configuration without printing secrets:

```bash
dle doctor
```

Connect this machine to a Descrybe account:

```bash
dle login
```

`dle login` discovers Descrybe OAuth metadata, registers a local public OAuth
client, starts a one-shot callback server on `127.0.0.1`, opens Descrybe login
in your browser, exchanges the callback code for tokens, and stores the token
set under the selected profile.

For terminal-only or remote-shell environments:

```bash
dle login --no-browser
```

List the MCP tools available to the connected user:

```bash
dle list-tools
```

Remove local tokens:

```bash
dle logout
```

`dle auth-url` is available as an advanced/debug helper for registered OAuth
clients. Most users should use `dle login`.

## Python Usage

```python
from descrybe_legal_engine import LegalEngine

client = LegalEngine.with_user_access_token(user_access_token)

results = client.call_tool(
    "search_cases_by_concept",
    {
        "term": "qualified immunity clearly established law",
        "search_focus": "general",
        "sort": "authority",
    },
)
```

For web apps, do not pass one global token to the client. Resolve the current
app user, load that user's Descrybe OAuth connection, and build a client for
that user only.

Local token storage prefers the operating system credential store when
`keyring` is installed. Otherwise it falls back to a permission-locked file
under the user's config directory. Web apps should store refresh tokens
encrypted in their own database, keyed to the app user.

The stored local token set includes the Descrybe-issued refresh token and OAuth
client id needed to rotate access tokens. The SDK sends short-lived access
tokens to the MCP endpoint and refreshes them automatically when possible.

## Examples

A small browser-based OAuth example lives in `examples/simple-web-app`. It
shows per-user Descrybe connection, encrypted server-side token storage, and
one `search_cases_by_concept` tool call.

```bash
cd examples/simple-web-app
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python app.py
```

The final command starts a local web server. While it is running, open
`http://127.0.0.1:8000` in a browser. Use `Ctrl+C` in the terminal to stop the
server.

You need a Descrybe account with Legal Engine access. If you do not have one
yet, start at https://descrybe.com/connect.

## Service Access

The SDK code is licensed under Apache 2.0. Access to the Descrybe Legal Engine
service is separate and requires a Descrybe account, applicable subscription or
entitlement, OAuth consent, and compliance with Descrybe's service terms and
rate limits. See [SERVICE_ACCESS.md](SERVICE_ACCESS.md).

## Project Hardening

- Security policy: [SECURITY.md](SECURITY.md)
- Security model: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md)
- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Release checklist: [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md)
- Live smoke test: [docs/LIVE_SMOKE_TEST.md](docs/LIVE_SMOKE_TEST.md)
- Changelog: [CHANGELOG.md](CHANGELOG.md)

## Defaults

- OAuth issuer: `https://api.descrybe.com`
- MCP endpoint: `https://mcp.descrybe.com/mcp`
- OAuth scope: `connect:mcp:read`
