Skip to content

OpenContracts

OpenContracts

The open source platform for building knowledge bases that humans and AI agents can work with together
Backend coverage backend
Frontend coverage frontend
Meta code style - black types - Mypy imports - isort License - MIT

OpenContracts is an MIT-licensed, self-hosted document analytics platform. Teams build knowledge bases from their documents and AI agents work alongside humans to search, analyze, and extend that knowledge.

What Does it Do?

OpenContracts gives you, in one place:

  1. Document collections organised as corpuses with folder hierarchies, fine-grained permissions, full history, and forking.
  2. Multi-format ingestion — PDF (layout-faithful, via Docling), DOCX (via Docxodus), and plain text. See Supported File Formats.
  3. Pluggable parser / embedder / thumbnailer pipeline — register your own in Python (see Pipeline Overview).
  4. Custom metadata schemas — typed fields with validation. See Metadata Overview.
  5. Human annotation interface — multi-page text annotations, document-level type labels, relationships, notes, and structural annotations (auto-extracted by the parser).
  6. AI agents — configurable agents built on PydanticAI that search documents, query annotations, and participate in discussions. See LLM Framework.
  7. MCP server — expose your corpus to Claude, Cursor, and any MCP-compatible AI tool via streamable HTTP (and a deprecated SSE transport). See MCP.
  8. Data extract — ask multiple questions across hundreds of documents using Fieldset / Column / Extract records. See Data Extraction.
  9. Forum-style discussions — global, per-corpus, and per-document threads with voting, moderation, @-mentions of documents/corpuses/agents, and badge-based reputation. See Commenting System.
  10. Corpus actions — automation triggers that run a fieldset, analyzer, or agent when a document is added / edited or a discussion thread / message arrives. See Corpus Actions.
  11. Document versioning & forking — version-controlled corpuses; fork a public corpus to build on someone else's work.
  12. Multimodal search — combined vector embeddings (pgvector) and full-text search over documents and annotations.

Grid Review And Sources.gif

Key Docs

  1. Quickstart Guide — get running with Docker.
  2. Key Concepts — the data model and core workflows.
  3. Metadata System — define custom metadata schemas.
  4. PDF Annotation Data Format — how text maps to PDF coordinates (PAWLs).
  5. LLM Framework — PydanticAI integration, tools, agents.
  6. Vector Store Architecture — pgvector-backed semantic search.
  7. Write Custom Data Extractors — extend the extraction pipeline.

Architecture at a Glance

Core Data Standard (PAWLs)

OpenContracts uses a portable text-and-layout format derived from AllenAI's PAWLs project — tokens with bounding boxes per page, so annotations carry both their text and their visual position:

Data Format

Processing Pipeline

The modular pipeline supports custom parsers, embedders, and thumbnail generators. Documents flow through three stages: parse → thumbnail → embed.

Pipeline Diagram

License

OpenContracts is released under the MIT License. Build proprietary products on it, embed it in commercial offerings, fork it, ship it — no copyleft strings attached.

Acknowledgements

This project builds on work from AllenAI PAWLS (PDF annotation data format and concepts).