descrybe-legal-engine 0.1.0

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

Descrybe Legal Engine Python

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

pip install descrybe-legal-engine

For local development from this repository:

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:

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:

dle doctor

Connect this machine to a Descrybe account:

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:

dle login --no-browser

List the MCP tools available to the connected user:

dle list-tools

Remove local tokens:

dle logout

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

Python Usage

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.

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.

Project Hardening

• Security policy: SECURITY.md
• Security model: docs/SECURITY_MODEL.md
• Contributing guide: CONTRIBUTING.md
• Release checklist: docs/RELEASE_CHECKLIST.md
• Live smoke test: docs/LIVE_SMOKE_TEST.md
• Changelog: CHANGELOG.md

Defaults

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