Judicex

Open-source legal AI software for evidence-grounded drafting, matter

management and AI-assisted legal work — with an answer contract that

fails closed instead of hallucinating.

Judicex is a workspace for lawyers and legal teams. You can ingest official sources and private matter files, run deterministic workflow checks, generate drafts in a Word-style split-view editor, and chat with an LLM whose answers are bound to the evidence in a SQLite knowledge base you control.

The project ships with a Flask web UI, a CLI, and an MCP stdio server, and talks to Ollama, OpenAI, Anthropic, OpenAI-compatible providers — or runs with no LLM at all.

Open-source vs. cloud. This repository is the open-source build of

Judicex: install it on your laptop, on a workstation, or on a private

server inside the firm. A managed cloud version with hosted multi-tenant

deployment, SSO and audit features is on the roadmap as a separate

offering; this codebase is and will remain Apache-2.0.

---

Why Judicex

Most legal AI products today are either:

• Closed SaaS that ship your client data to a vendor (Harvey, Legora, …), or
• Generic RAG demos that paste retrieved chunks into a prompt and hope.

Judicex takes a different bet. In legal work, the value is not in the prompt — it is in the **structured, verifiable evidence the answer stands on**. So the codebase is organised around that idea:

• Two evidence layers, never confused.

Legal sources (documents, documentversions, legalatoms, entities, edges) are the only thing that can produce citations. Operational notes (agent_memories) store preferences, decisions and lessons — they shape how the agent works, but are never cited as law.

• Versioned official sources.

Real ingestion from Normattiva with URN extraction, versioned over time (effectivefrom / effectiveto) so you can ask “what did this article say on date X?” instead of pretending the law is timeless.

• Answer contract that fails closed.

answercontract.py + numericverifier.py + confidence.py enforce the states grounded / limited / abstain / chat with JSON-schema validation, citations bound to retrieved document_ids only, and temperature 0. If evidence is insufficient, Judicex abstains. It does not improvise.

• Workflow packs as data.

Matter-analysis profiles (e.g. civil debt recovery, opposition to injunctions, generic file review) are JSON workflow packs, versioned and swappable per vertical / firm — not application logic.

• You control where it runs.

SQLite, Flask, vanilla JS, no external build step. The same codebase runs on a single workstation or on a private server inside the firm. Matter data lives in the SQLite database and the attachment directory you point Judicex at — nothing leaves the host until you explicitly point a chat at a hosted LLM.

This repository is v0.2.0-alpha: a usable prototype, not production SaaS.

Features

Sources & evidence

• Local SQLite knowledge base with versioned document history and legal

atoms.

• One-click import of official source bundles (Normattiva-driven).
• Two-tier evidence model: legal sources (citable) and operational notes

(style and decisions).

Matters & files

• Private matters, folders, versioned matter documents.
• Upload PDF, DOCX, text, markdown, CSV, JSON, images.
• PDF / image preview, stored-text viewer, OCR via Ollama.
• Matter facts, timelines, parties, amounts and deadlines extracted

deterministically.

Workflows & analysis

• matter_analysis against a thesis: explicit proof profile, present /

partial / missing elements, next actions.

• Built-in workflow packs and a custom workflow builder.
• Tabular review with editable cells, filtering, sorting, saved views and

CSV / XLSX / DOCX export.

Drafting

• Built-in templates plus a custom template editor.
• Split-view drafting page (Claude- / ChatGPT-artifact style):

instruction column on the left, live Word-style document preview on the right.

• Generate, save into the matter, copy, export to DOCX / PDF.

AI surface

• Persisted chat sessions (sidebar, deletable).
• Multi-provider: Ollama, OpenAI, Anthropic, OpenAI-compatible, no-LLM.
• Grounded answer engine with citations bound to evidence.
• MCP stdio server for integration with MCP-aware clients.
• CLI utilities (judicex, judicex-mcp, judicex-agent, judicex-web).

Privacy & ops

• Local password gate, backup and restore, optional matter-file

encryption.

• API keys stay in .env / shell, never in the browser.

Screenshots

Drop PNGs into docs/screenshots/ and reference them here once you

publish: docs/screenshots/drafts-split-view.png,

docs/screenshots/matter-analysis.png, etc. They are intentionally not

committed yet — the repository is currently text-only to keep diffs clean.

Architecture at a glance

┌──────────────────────────────┐    ┌──────────────────────────────┐
│  Web UI (Flask + vanilla JS) │    │  CLI / MCP stdio / Agent     │
└──────────────┬───────────────┘    └──────────────┬───────────────┘
               │                                   │
               ▼                                   ▼
        ┌─────────────────────────────────────────────────┐
        │            agent_runtime + answering            │
        │  intent router → tools → answer_contract → out  │
        └────────────┬───────────────────────┬────────────┘
                     │                       │
                     ▼                       ▼
        ┌──────────────────────┐  ┌────────────────────────┐
        │  llm_provider.py     │  │  store.py (SQLite)     │
        │  ollama / openai /   │  │  documents, atoms,     │
        │  anthropic / oai-c / │  │  entities, edges,      │
        │  none                │  │  matters, agent notes  │
        └──────────────────────┘  └────────────────────────┘

See docs/ARCHITECTURE.md for the full layer description and database tables, and docs/JUDICEXPRODUCT_STRATEGY.md for the product thesis.

Quick start

git clone https://github.com/JustVugg/judicex.git
cd judicex
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[crypto]"
cp .env.example .env
judicex init-db --db ./memory.db judicex web --db ./memory.db --area civile --port 5051

Then open .

For OCR on scanned PDFs:

pip install -e ".[crypto,ocr]"

AI provider setup

Judicex reads provider settings from the in-app Settings page and from environment variables. API keys are kept out of the frontend on purpose.

Local Ollama (default, fully offline):

ollama serve
ollama pull qwen2.5:7b

JUDICEXLLMPROVIDER=ollama
OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=qwen2.5:7b
JUDICEXOCRMODEL=glm-5:cloud

OpenAI:

JUDICEXLLMPROVIDER=openai
OPENAIAPIKEY=...
OPENAI_MODEL=gpt-4.1-mini

Anthropic / Claude:

JUDICEXLLMPROVIDER=anthropic
ANTHROPICAPIKEY=...
ANTHROPIC_MODEL=claude-3-5-sonnet-latest

OpenAI-compatible (LocalAI, vLLM, hosted compatible APIs):

JUDICEXLLMPROVIDER=openai_compatible
OPENAICOMPATIBLEAPI_KEY=...
OPENAICOMPATIBLEBASE_URL=http://127.0.0.1:8000/v1
OPENAICOMPATIBLEMODEL=local-model

No-LLM mode also works: deterministic matter analysis, draft templates, search and audit still run.

Demo & CLI

Synthetic demo database:

python scripts/create_demo.py --db ./memory.demo.db
judicex web --db ./memory.demo.db --area civile --port 5051

CLI examples:

judicex matter-create   --db ./memory.db --title "Recupero credito Beta" \
                        --client-name "Alfa S.r.l." --area civile
judicex matter-add-doc  --db ./memory.db --matter-id "matter:..." \
                        --file ./examples/demo_matter.md --kind memo
judicex matter-context  --db ./memory.db --matter-id "matter:..." \
                        --query "fattura pagamento"
judicex list-workflow-packs --db ./memory.db
judicex matter-analyze  --db ./memory.db --matter-id "matter:..." \
                        --thesis "ricorso per decreto ingiuntivo"
judicex ask             --db ./memory.db --provider ollama --model qwen2.5:7b \
                        --area civile --matter-id "matter:..." \
                        --question "Che elementi mancano?"

Operational notes are separate from legal sources. Legal sources hold statutes, official documents, legal atoms and citations; operational notes hold how the assistant should work — preferences, decisions, lessons, recurring strategies, and matter-specific notes.

judicex memory-add    --db ./memory.db --kind preference \
                      --title "Stile recupero crediti" \
                      --content "Per recupero crediti B2B usa tono pratico." \
                      --tag recupero_crediti --importance 0.9
judicex memory-search --db ./memory.db --query "recupero crediti"

Self-host or cloud — your call

The open-source build is designed to run wherever you install it:

• On a single workstation, with a local LLM via Ollama, for a sole

practitioner who wants zero recurring cost.

• On a private server inside the firm, behind a real WSGI stack, VPN and

backups (see SECURITY.md for the hardening checklist).

• On any cloud you operate yourself — the codebase has no hard dependency

on a specific provider.

A managed cloud version of Judicex (multi-tenant, SSO, hosted upgrades) is on the roadmap as a separate offering. This repository remains Apache-2.0; the cloud product is built on top of it, not in place of it.

Project layout

judicex/
├── judicexmemoryos/        # Python package (engine, store, agent, web)
│   ├── store.py              # SQLite schema, persistence, search
│   ├── web_app.py            # Flask routes & JSON APIs
│   ├── agent_runtime.py      # tool-calling agent loop
│   ├── answering.py          # grounded answer pipeline
│   ├── answer_contract.py    # claim/citation/numeric validation
│   ├── matter_analysis.py    # deterministic matter workflow analysis
│   ├── llm_provider.py       # Ollama / OpenAI / Anthropic / compatible
│   ├── mcp_stdio.py          # MCP stdio server entry point
│   ├── cli.py                # judicex CLI
│   ├── workflow_packs/       # JSON workflow packs
│   ├── templates/            # Flask + draft templates
│   └── static/               # Vanilla JS UI
├── tests/                    # unittest suite
├── benchmarks/               # public benchmark fixtures
├── docs/                     # architecture, strategy, installers
└── scripts/                  # dev / test / installer / demo helpers

The Python package is named judicexmemoryos for historical reasons; the product is just Judicex.

Development

For local development, install the package in editable mode and run the standard test script. The tests use Python's built-in unittest; no pytest dependency is required.

pip install -e ".[crypto,test]"
scripts/dev.sh
scripts/test.sh
python scripts/runpublicbenchmark.py --db ./memory.benchmark.db

The web UI is server-rendered Flask plus static JavaScript. There is **no TypeScript, Next.js, Supabase or external frontend build step** — and there is no plan to add one. Contributions that require one will be politely declined.

Simple local installers

• Windows: powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1
• macOS: bash scripts/install_macos.sh

See docs/INSTALLERS.md.

Repository hygiene before publishing

The included .gitignore excludes the things that must not end up on GitHub. Before your first push, double-check that none of these are tracked:

• .env
• memory.db and any other .db / .sqlite* files
• memory_files/, uploads/, private/
• API keys, real client documents, screenshots with private data

A pre-publish checklist is documented in SECURITY.md.

Roadmap

See ROADMAP.md. Highlights:

• Better PDF viewer with page thumbnails and annotation coordinates (v0.3)
• Rich document editor with version diff and accept/reject (v0.4)
• Optional auth layer + desktop packaging (v0.5)
• Multi-user workspace + RBAC + audit export (later)

Contributing

Contributions are welcome — see CONTRIBUTING.md. The general rules:

• Keep the stack Flask / Python / HTML / JavaScript / SQLite.
• Never commit private legal documents, real databases, uploads or API

keys.

• Add or update tests for changes touching API behavior, persistence or

workflows.

• Keep provider integrations behind llm_provider.py.

License

Apache License 2.0 — see LICENSE and NOTICE. Apache-2.0 was chosen because it is permissive and includes an explicit patent grant, which matters for a domain that intersects regulated work.

Disclaimer

Judicex is a software assistant for legal drafting, document organization and evidence-grounded answering. **It does not provide legal advice and does not replace a qualified legal professional.** Outputs may be incomplete, incorrect, outdated or unsuitable for a specific jurisdiction. See DISCLAIMER.md.

Security

To report a vulnerability, please follow SECURITY.md. Do not open public issues with exploit details.

---

If you build something on top of Judicex — a vertical pack for criminal law, a richer drafting UI, an integration with case-management software — please open an issue or a PR. The point of an open-source legal AI is that the verticals are built in the open, not behind a sales NDA.