Hermes Legal Advisor

Free, multi-provider AI contract analysis for developers, freelancers, and small teams.

Feed it a contract - a .txt, .pdf, or .docx file - and it reads every clause, scores each one for risk, tells you which standard clauses are missing, suggests concrete replacement language for the risky ones, and gives you a final SIGN / NEGOTIATE / REJECT verdict. It remembers every contract it has ever analyzed, so it can tell you when a recurring counter-party's terms are getting worse over time.

It works with zero budget: a built-in offline rule engine needs no API key at all, and free tiers on Groq and Google Gemini give you full LLM-grade analysis at no cost. If you have a paid API key for a stronger model, you can plug that in too - it is always optional, never required.

Why this exists

Contract review tools either live inside a specific AI coding assistant, cost money per review, or only handle plain text. Hermes Legal Advisor is a standalone command-line tool and Python package: install it, point it at a real contract file, and get a structured answer - no subscription, no vendor lock-in, and it plugs straight into your GitHub workflow as a CI check.

Key Features

Risk Scoring

Install

pip install hermes-legal-advisor[all]

[all] pulls in every optional dependency (PDF/DOCX support, Groq, Gemini, OpenRouter clients). If you only need one provider, install a narrower extra instead, e.g. pip install hermes-legal-advisor[groq,pdf].

Or run from source:

git clone https://github.com/Lethe044/hermes-legal.git
cd hermes-legal
pip install -e ".[all]"

Pick a free provider

You do not need to configure anything to get started - the offline scanner always works. For deeper LLM-backed analysis, pick one:

# Groq - free tier, very fast
export GROQ_API_KEY=gsk_...          # https://console.groq.com/keys

# Gemini - generous free tier
export GEMINI_API_KEY=...            # https://aistudio.google.com/apikey

# OpenRouter - access to many :free models, plus paid ones if you want them
export OPENROUTER_API_KEY=sk-or-...  # https://openrouter.ai/keys

# Ollama - fully local, fully private, needs no internet after setup
ollama pull llama3.1 && ollama serve

Hermes Legal Advisor auto-detects whichever of these is configured, in that order, and falls back to the offline scanner if none are. Check what it sees:

hermes-legal providers

See docs/PROVIDERS.md for a full comparison and setup walkthrough.

Quick Start

hermes-legal analyze sample_contracts/freelance_contract.txt
hermes-legal analyze sample_contracts/nda_contract.txt --perspective vendor
hermes-legal analyze contract.pdf --output report.md --redline redline.md
hermes-legal analyze contract.docx --redline-docx redline.docx

Batch mode

hermes-legal batch ./contracts_folder

Produces a batch_summary.csv, a visual dashboard.html (opened automatically unless you pass --no-browser), and one Markdown report per file.

Scripting / CI integration

hermes-legal analyze contract.txt --format json

Prints the full structured result as JSON to stdout instead of a formatted table - pipe it into jq, a script, or another tool.

Version comparison

hermes-legal compare sample_contracts/freelance_contract.txt sample_contracts/freelance_contract_v2.txt

Watch mode

hermes-legal watch ./contracts_inbox
hermes-legal watch ./contracts_inbox --webhook https://hooks.slack.com/services/... --alert-on CRITICAL,HIGH

The --webhook flag posts an alert to Slack or Discord whenever a newly dropped contract scores one of the risk levels in --alert-on (default: CRITICAL and HIGH).

Ask a contract a direct question

hermes-legal ask contract.pdf "what is the termination notice period?"

With an LLM provider configured, this grounds the answer in the actual contract text. With the offline provider, it falls back to a free keyword search over the document instead of guessing.

Plain-English explanations

hermes-legal analyze contract.txt --explain

Adds an "In Plain English" section translating each flagged clause's legal language into everyday terms - useful for anyone who isn't a lawyer.

Track deadlines across every contract

hermes-legal deadlines

Lists term lengths, auto-renewal cancellation windows, and termination notice periods extracted from every contract you've analyzed, soonest first - so you don't have to reread old contracts to remember what's coming up.

Portfolio dashboard

hermes-legal portfolio

Generates an HTML dashboard aggregating every contract you've ever analyzed: risk distribution, your most common red flags, and a per-counter-party breakdown with their highest risk seen and latest verdict. Useful for anyone tracking more than a handful of contracts.

Contract packages (main agreement + exhibits)

hermes-legal analyze main_agreement.pdf --include exhibit_a.pdf --include exhibit_b.docx

Merges the main file with any number of --include attachments and analyzes them as a single contract package.

Skip redundant API calls

hermes-legal analyze contract.txt --force

By default, re-analyzing the exact same contract text reuses the cached result instead of calling a paid or rate-limited API again. Pass --force to bypass the cache, or --no-cache to disable caching for one run without affecting future runs.

True inline redlines (edits your actual .docx)

hermes-legal analyze contract.docx --redline-inline redlined_contract.docx

Unlike --redline-docx (a separate memo), this inserts each suggestion directly into a copy of your original document, right after the clause it concerns - closer to what a human reviewer would hand back.

True inline redlines (edits your actual .docx)

hermes-legal analyze contract.docx --redline-inline redlined_contract.docx

This inserts each suggestion as a real Word Tracked Change directly into a copy of your original document, right after the clause it concerns. Open the result in Word and it shows up in the Review pane exactly like a human editor's tracked edit - accept, reject, or comment on each one individually.

Organize by client or matter

hermes-legal analyze contract.txt --client "Acme Corp"
hermes-legal clients
hermes-legal history --client "Acme Corp"
hermes-legal portfolio --client "Acme Corp"

Tag any analysis with --client, then filter history, the portfolio dashboard, or a batch run to just that client - useful the moment you're handling more than one.

Excel batch reports

hermes-legal batch ./contracts_folder --output-xlsx summary.xlsx

Produces a color-coded Excel workbook (risk and verdict cells shaded) alongside the usual CSV and HTML dashboard. Requires pip install hermes-legal-advisor[xlsxreport] (included in [all]).

Run it with Docker

docker build -t hermes-legal .
docker run -p 8765:8765 -v hermes_data:/data hermes-legal

Starts the web dashboard at http://localhost:8765 with zero local Python setup. Add -e GROQ_API_KEY=... (or Gemini/OpenRouter) for LLM-backed analysis, or leave it out to use the free offline scanner. The mounted volume persists analysis history across container restarts.

Protect the dashboard with an API key

hermes-legal serve --host 0.0.0.0 --api-key mysecret

Required if you expose serve beyond 127.0.0.1 (a shared server, a Docker container on a network others can reach). Every API call needs X-API-Key: mysecret, or you can open http://host:8765/?key=mysecret and the page fills it in automatically. Can also be set via HERMES_LEGAL_API_KEY.

Speed up large batches

hermes-legal batch ./contracts_folder --parallel 5

Analyzes multiple contracts concurrently instead of one at a time - mainly useful with a hosted provider (Groq, Gemini, OpenRouter) where each analysis is a network call. Defaults to sequential (--parallel 1).

Bundle everything for a client

hermes-legal export --client "Acme Corp" --output acme_bundle.zip

Zips every stored report, a CSV summary, and an HTML dashboard for one client (or everyone, if --client is omitted) into a single file ready to email or archive.

Scanned PDFs (OCR)

hermes-legal analyze scanned_contract.pdf

If a PDF has no extractable text, Hermes falls back to OCR automatically. This needs the optional ocr extra (pip install hermes-legal-advisor[ocr], included in [all]) plus the system packages tesseract-ocr and poppler-utils (already included in the Docker image). Pass --no-ocr to skip it and get an error instead.

Privacy mode for hosted providers

hermes-legal analyze contract.pdf --provider groq --redact --redact-name "Acme Corp" --redact-name "Jane Doe"

Before any text is sent to a hosted provider (Groq, Gemini, OpenRouter), emails, phone numbers, IBANs, card and ID numbers, and every name you list with --redact-name are replaced with placeholders like [EMAIL_1] and [PARTY_1]. Legal terms, dates, and amounts stay intact so the analysis is unaffected. Local providers (offline, Ollama) never send text anywhere, so they always get the original. This is a best-effort pattern-based safety net, not a guarantee: for truly privileged material, stay on the offline scanner or a local Ollama model.

Model clauses

hermes-legal clause
hermes-legal clause Liability

Browse balanced starting-point replacement clauses for every category the engine checks. The same language is attached automatically to flagged clauses in Markdown, PDF, DOCX and Word Track Changes redlines. They are templates to adapt, not legal advice.

Check your setup

hermes-legal doctor

Lists which optional features are ready (providers, OCR, PDF/Excel/DOCX support, local models) and what is missing. API key values are never shown.

See exactly what changed between drafts

hermes-legal compare v1.txt v2.txt --text

Adds a line-by-line diff of the actual contract text on top of the per-clause score comparison.

Use it from an AI assistant (MCP)

hermes-legal mcp --provider offline --allow-dir ~/Contracts

Starts a Model Context Protocol server over stdio, so an assistant that supports MCP can analyze contracts, ask questions about them, fetch model clauses and read your saved history. To use it with Claude Desktop, add this to its MCP configuration:

{
  "mcpServers": {
    "hermes-legal": {
      "command": "hermes-legal",
      "args": ["mcp", "--provider", "offline", "--allow-dir", "/path/to/Contracts"]
    }
  }
}

It exposes five tools: analyze_contract, ask_contract, get_model_clause, contract_history and list_deadlines.

Because text inside a document can try to manipulate an assistant, some choices are deliberately made by you, not by the assistant:

• The provider and privacy mode (--provider, --redact, --redact-name) are set when you start the server. The assistant cannot pick a hosted provider or turn redaction off.
• Files can only be read from folders you list with --allow-dir (or HERMES_LEGAL_MCP_ALLOW_DIRS). With none listed, only the current folder is allowed.
• Analyses are not saved to your history unless the assistant asks to.

Set your defaults once (config file)

hermes-legal config init
hermes-legal config show

config init writes a fully commented-out ~/.hermes-legal/config.yaml. Uncomment what you want, for example:

provider: groq
perspective: client
redact: true
redact_names: ["Acme Corp"]

Every command that has the matching option then uses it by default. Anything you type on the command line wins, and --no-redact / --no-explain switch a default off for a single run. A mistyped or invalid value is ignored with a warning on stderr, never a crash.

Analyze a whole folder tree

hermes-legal batch ./clients --recursive

Walks sub-folders too. Reports are named after the relative path, and the reports folder itself is never re-analyzed.

Chat mode

hermes-legal chat

Web dashboard (no CLI needed)

hermes-legal serve

Opens a browser tab at http://127.0.0.1:8765 where anyone can drag and drop a contract file and get an instant analysis - built for colleagues or clients who will never touch a terminal. Uses only Python's standard library, so it needs no extra install.

Generate a new contract

hermes-legal generate --list
hermes-legal generate nda --field party_a="Acme Inc." --field party_b="Beta LLC" --output nda.txt
hermes-legal generate freelance --interactive

Produces a ready-to-edit draft entirely offline, for free. Any field you don't supply is left as a clearly marked placeholder.

Customize for your firm

hermes-legal playbook init

Writes an example ~/.hermes-legal/playbook.yaml you can edit to set your firm name, override any clause's risk score or negotiation language, add entirely custom red-flag rules, or adjust the CRITICAL/HIGH/MEDIUM thresholds - all without touching a line of code. Every analyze, batch, and serve command picks it up automatically if present, or point at a specific file with --playbook path/to/file.yaml.

Professional PDF reports

hermes-legal analyze contract.pdf --output-pdf report.pdf

Requires pip install hermes-legal-advisor[pdfreport] (included in [all]).

Use it in CI

Drop this into any repository to get an automatic risk summary whenever a contract file changes in a pull request:

# .github/workflows/contract-review.yml
on:
  pull_request:
    paths: ["contracts/**"]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write  # lets the action comment on the PR
    steps:
      - uses: actions/checkout@v4
      - uses: Lethe044/hermes-legal@main
        with:
          path: contracts/
          fail-on-risk: CRITICAL
          groq-api-key: ${{ secrets.GROQ_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

No API key configured? Leave the groq-api-key line out entirely - the action still runs, using the offline scanner. No github-token? The action still writes the risk summary to the job's step summary - it just won't post (or update) a comment directly on the pull request.

Automatic Red Flags

The offline scanner checks 18 clause categories in English, Turkish, Spanish and German. Red flags it looks for include:

• Termination notice under 7 days
• Uncapped liability
• Broad "any and all claims" indemnification
• Terms one party may change on its own, without the other's agreement
• Assignment to a third party without consent
• Exclusivity that stops one party working with anyone else
• IP assignment covering personal-time work
• Non-compete longer than 2 years or with worldwide scope
• Non-solicitation longer than 2 years
• Auto-renewal with under 30 days' cancellation window
• Daily or weekly penalties and liquidated damages
• Warranties disclaimed or work provided "as is"
• Personal data shared with third parties without limits
• Arbitration/dispute costs borne entirely by one party
• Perpetual/indefinite confidentiality obligations

It also reports which standard clauses a contract of that type is missing (checked against the text itself, in its own wording), and the overall risk is never lower than the worst single clause warrants.

Project Structure

hermes-legal/
├── src/hermes_legal/
│   ├── providers/     # Groq, Gemini, OpenRouter, Ollama, offline rule engine
│   ├── ingest/         # .txt / .pdf / .docx readers
│   ├── analysis/       # orchestration, risk scoring, version diff
│   ├── reports/        # Markdown, CSV, DOCX redline generation
│   ├── memory/         # JSONL-backed contract history
│   ├── cli.py          # every command, see docs/COMMANDS.md
│   ├── generator.py    # offline contract templates (NDA, freelance, employment, service)
│   ├── playbook.py     # firm-specific YAML customization
│   ├── config.py       # default options from ~/.hermes-legal/config.yaml
│   ├── extract.py      # party names and key terms, offline
│   ├── redact.py       # privacy mode
│   ├── clause_library.py  # model replacement clauses
│   ├── mcp_server.py   # MCP server for AI assistants
│   ├── webapp.py        # zero-dependency local web dashboard
│   ├── watch.py
│   └── chat.py
├── tests/
├── sample_contracts/
├── action.yml           # GitHub Action definition
└── docs/

Documentation

• docs/SETUP.md - installation and configuration in depth
• docs/COMMANDS.md - every command and option (generated from the real parser)
• docs/PROVIDERS.md - free-tier provider comparison and setup
• docs/ADVANCED.md - the project's origin as a Hermes/Atropos hackathon entry, and the reinforcement-learning reward function used to train it
• CONTRIBUTING.md - how to add a provider, a rule, or a report format
• CHANGELOG.md - version history
• SECURITY.md - supported versions and how to report a vulnerability
• CODE_OF_CONDUCT.md - community standards

Contributing

Issues and pull requests are welcome - see CONTRIBUTING.md for the shape of a good contribution (a new red-flag pattern, a new provider, a new report format are all good first PRs).

Disclaimer

Hermes Legal Advisor provides contract analysis, not legal advice. Always consult a qualified attorney before signing any contract.