> For the complete documentation index, see [llms.txt](https://docs.meganova.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meganova.ai/libra-os/use-cases/legal-research-assistant.md).

# Legal Research Assistant

Build a matter copilot that answers a lawyer's questions from the **matter's own documents** and **live case-law research**, and backs every answer with citations — the way a diligent associate would.

This guide exercises the three levers from the [Use Cases overview](https://docs.meganova.ai/libra-os/use-cases.md): model tiers, grounding, and domain guardrails. By the end you'll have a deployable `legal-assistant` persona.

***

## What you're building

> *"On this employment matter, has any Ontario court found a termination clause enforceable post-Waksdale? Summarise the matter's key dates, and flag anything in our uploaded contract that mirrors the clauses courts struck down."*

A good answer to that needs three things a raw chat model can't do alone:

* read the **matter's uploaded documents** (the contract, correspondence),
* run **current legal research** on the open web (case law moves), and
* **cite** every claim so the lawyer can verify — and never invent a case.

Libra OS delivers this as one persona with knowledge, research, and citation grounding wired together.

## How Libra OS delivers it

| Need                            | Libra OS piece                                                               |
| ------------------------------- | ---------------------------------------------------------------------------- |
| Read the matter's documents     | A **knowledge collection** the persona is bound to                           |
| Current case-law research       | The **`deep_research`** skill (multi-aspect web research with citations)     |
| Cite everything                 | Grounded **`citations`** on the response (`[source:…]` + a References list)  |
| Show client names in the answer | The **`pii_redactor`** guardrail, turned *off* for this persona              |
| Plan what to do per question    | The **brain** (a fast planner) routing between knowledge lookup and research |

***

## Step 1 — Create the persona

Register the agent through the managed API (or drop the markdown in your agents directory). The frontmatter is the whole configuration:

```yaml
---
name: legal-assistant
agent_type: persona
brain: true                     # plan per question (lookup vs research)
capabilities:
  - document_search             # read the matter's knowledge collection
  - deep_research               # current case-law research
  - web_research
skills:
  - skill_deep_research
knowledge_bindings:
  - matter-{{matter_id}}        # bind to this matter's collection
guardrails:
  pii_redactor: disabled        # a lawyer must see client names in the answer
model: anthropic/claude-opus-4-7    # answer tier — reader-facing legal prose
max_turns: 8
---

# Legal Assistant

You are a legal research assistant for a practising lawyer. Ground every
statement in the matter's documents or in retrieved case law, and cite the
source after each factual claim. If the evidence does not support a claim,
say so plainly — never invent a case name, citation, or holding.
```

> **Why `pii_redactor: disabled` here.** By default Libra OS scrubs emails, phone numbers, and names from model inputs and outputs. That's wrong for a matter answer — the lawyer *must* see their client's name. Disable it **only** on personas whose workflow legitimately handles the raw names. Leave it on everywhere else.

## Step 2 — Add the matter's documents

Create the matter's collection once, then upload the contract, pleadings, and correspondence into it. (A collection must exist before you upload; the upload field is `collection_id`.) Libra OS extracts text, chunks, embeds, and indexes automatically; scanned PDFs are OCR'd.

```bash
# 1. Create the matter collection (once)
curl -X POST "$LIBRA_OS_URL/api/knowledge/collections" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "matter-12345", "access_level": "private"}'

# 2. Upload the matter's documents (field is collection_id)
curl -X POST "$LIBRA_OS_URL/v1/managed/documents/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "collection_id=matter-12345" \
  -F "file=@employment-agreement.pdf"
```

The persona's `knowledge_bindings` scopes retrieval to this matter — one lawyer's matter can never retrieve from another's.

## Step 3 — The settings that matter

Three tiers, then two knobs specific to legal research.

**Model tiers.** Set them once, globally, and every persona inherits them:

| Tier       | Role                                                                            | Pick                                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Brain**  | Plans each turn (lookup vs research). Runs first, in the latency-critical path. | A **fast, non-thinking** model (a Flash-lite / Flash tier). *Avoid* thinking models — they burn the budget reasoning and return empty or slow plans. |
| **Answer** | Writes the lawyer-facing prose.                                                 | A **premium** model (an Opus / Pro tier).                                                                                                            |
| **Skill**  | Retrieval loops + research synthesis.                                           | A **fast, cheap** model (a Flash / Haiku tier).                                                                                                      |

**Research depth and timeouts.** Broad case-law questions pull many sources; give research room to synthesise them:

* `LIBRA_OS_DEEP_RESEARCH_TIMEOUT` (default `150s`) — the overall budget for a multi-aspect research run. Raise it for very broad questions.
* `LIBRA_OS_DEEP_RESEARCH_MAX_EVIDENCE_CHARS` (default `32000`) — how much evidence each aspect feeds the synthesis step. Lower = faster; raise for deeper coverage.

If research ever times out, Libra OS returns the **sources it did gather** with a note, rather than an empty answer — so the lawyer always gets citations to follow.

**Grounding.** Keep citations on. The response carries `output_segments` + `citations` (with a `cite_source` of `document` or `web`) so your UI can render clickable references. This is what turns "sounds right" into "here's the case."

## Step 4 — Ask it

```bash
curl -X POST "$LIBRA_OS_URL/agents/v1/$API_KEY/chat" \
  -H "Content-Type: application/json" \
  -H "X-Platform-User: firm-acme" -H "X-End-User: lawyer-jane" \
  -d '{
    "metadata": {"matter_id": "12345"},
    "messages": [{"role": "user",
      "content": "Has any Ontario court found a termination clause enforceable after Waksdale? Does our uploaded agreement mirror the struck-down language?"}]
  }'
```

A good answer weaves the two evidence sources and cites both:

> *Post-Waksdale, Ontario courts have generally found termination clauses unenforceable where the "for cause" provision violates the ESA \[source: canlii.org/…]. However, in \[case] the clause survived because … \[source: canlii.org/…]. **Your matter's agreement** (§7.2) contains the same "sole discretion" language the court struck down in Waksdale \[source: employment-agreement.pdf].*

## Verify it works

Before you trust it on a live matter, check the three failure modes that matter for legal work:

1. **Grounding** — every factual sentence carries a `[source:…]`. No citation ⇒ treat the claim as unverified.
2. **No fabrication** — ask about a case you know isn't in the evidence. It must say "not confirmed in available sources," **not** invent a plausible-sounding citation. (The persona prompt above enforces this; verify it holds.)
3. **Scoping** — confirm a question on matter A never retrieves a document from matter B. Bindings + per-user identity (`X-Platform-User` / `X-End-User`) enforce this.

## Common pitfalls

* **Empty answer on a broad question.** Historically a verbose research query could exhaust the research budget and return nothing. If you see this, raise `LIBRA_OS_DEEP_RESEARCH_TIMEOUT`; the persona will also now fall back to returning gathered sources rather than an empty body.
* **`research_depth: "fast"` seems ignored.** The explicit `brain` control wins over the `research_depth` alias. If you set `metadata.brain: "always"` *and* `research_depth: "fast"` on the same call, the brain runs (deep path). To force the single-shot fast path, send `research_depth: "fast"` **without** `brain: "always"`.
* **Client names come back as `[REDACTED]`.** The outbound PII guardrail is still on for this persona — set `guardrails.pii_redactor: disabled` (Step 1).
* **Slow, empty plans.** The brain is on a *thinking* model. Move it to a fast non-thinking tier (Step 3).

## Next steps

* Generate a formal write-up from the same evidence with the **Research Report Generator** guide (coming soon).
* Extract structured fields (parties, dates, clause types) from the contract with **Structured Extraction** (coming soon).
* See the full endpoint surface in [Capabilities](https://docs.meganova.ai/libra-os/capabilities.md).
