OpenContracts Documentation

The OpenContracts routing system is a centralized architecture designed to synchronize the browser URL with application state. It is built around a single source of truth: the CentralRouteManager.

Key Principles

• Centralized Management: CentralRouteManager handles all URL $\leftrightarrow$ State synchronization, entity fetching, and canonical redirects.
• Explicit Route Patterns: Uses /c/ and /d/ prefixes to eliminate ambiguity between different entity types.
• Slug-First URLs: Provides SEO-friendly URLs with automatic redirection from IDs to slugs.
• Dumb Consumers: Route components are simplified; they only read reactive variables using useReactiveVar() and render the UI.
• Complete Viewer State: The URL encodes the full document viewer state, including both selections and visualization settings, enabling robust deep linking.

The OpenContracts frontend uses specific React components to handle real-time WebSocket interactions depending on the scope of the conversation:

• ChatTray: Used for document-specific conversations, typically rendered in the right sidebar of the document viewer. Located at frontend/src/components/knowledge_base/document/right_tray/ChatTray.tsx.
• CorpusChat: Used for corpus-wide conversations via a full-screen interface. Located at frontend/src/components/corpuses/CorpusChat.tsx.
• Thread Components: UI components for managing discussion threads. Located in frontend/src/components/threads/.

All these components follow a similar pattern for managing WebSocket connections, state, and UI rendering.

OpenContracts uses WebSockets to provide real-time, streaming conversations with AI agents. This architecture supports progressive streaming of answers, source citations, reasoning timelines, and tool approval workflows.

Key components include:

• Frontend (React): Uses components like ChatTray, CorpusChat, and ChatMessage to manage UI state (including Source Atom State).
• WebSocket Layer: Handles the message protocol and connection lifecycle.
• Backend (Django Channels): Uses specific consumers to manage different contexts:
  • UnifiedAgentConsumer: Manages all agent chat contexts (corpus, document, standalone).
  • ThreadUpdatesConsumer: Handles real-time thread/conversation updates.
  • NotificationUpdatesConsumer: Handles real-time user notifications.
• Data Layer: Persists conversations and messages in the database.

The Worker Upload System is a REST API designed for machine-to-machine workflows. It allows external pipelines, bulk ingestion scripts, and pre-processed document feeds to push documents, annotations, and embeddings into OpenContracts. This is ideal when documents have already been parsed and annotated outside of the standard OpenContracts pipeline.

Use cases:

• External processing pipelines: Integrating custom NLP pipelines.
• Bulk ingestion: Migrating large volumes of pre-annotated documents.
• Pre-processed documents: Uploading files where text extraction, layout analysis, and embeddings are already complete.

The notification system provides real-time alerts for important collaboration events, including replies, mentions, votes, badges, and moderation actions. It is built using a decoupled architecture consisting of:

• Notification Model: Stores records, read/unread status, and links to related objects (messages, conversations, actors).
• Signal Handlers: Automatically trigger notifications via Django post_save signals.
• GraphQL API: Provides queries for retrieval and mutations for management.
• WebSocket Support: Enables instant delivery via a real-time WebSocket connection.

The opencontractserver.llms module provides four primary entry points for interacting with LLM capabilities:

• agents (AgentAPI): The most common entry point. Used for creating and interacting with document and corpus agents, including structured data extraction.
• embeddings (EmbeddingAPI): Used for generating text embeddings.
• vector_stores (VectorStoreAPI): Used for creating and interacting with vector stores for similarity search.
• tools (ToolAPI): Used for creating and managing CoreTool instances.

from opencontractserver.llms import agents, embeddings, vector_stores, tools
from opencontractserver.llms.tools.tool_factory import CoreTool

The implementation of Global Embeddings must satisfy the following criteria to be considered successful:

• Annotation State: All new annotations must use the DEFAULT_EMBEDDER embedding. Corpus annotations configured with a custom embedder must maintain both the custom and the default embeddings.
• Search Functionality:
  • Global Search: Must return results across all accessible documents.
  • Corpus Search: Must prioritize and use corpus-specific embeddings when they are available.
• Data Integrity: Existing annotations must be backfilled with default embeddings, and all tests must pass.