### Install and Start Frontend Locally

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/quick_start.md

Navigate to the frontend directory and run these commands to install dependencies and start the frontend with hot reload enabled for active development.

```bash
$ cd frontend
$ yarn install
$ yarn start
```

--------------------------------

### Install Dependencies and Run Locally

Source: https://github.com/open-source-legal/opencontracts/blob/main/cloudflare-og-worker/README.md

Install project dependencies and start the local development server using npm. This is useful for testing the worker during development.

```bash
npm install

npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/manual-test-scripts/README.md

Command to start the development server for the frontend.

```bash
cd frontend && yarn start
```

--------------------------------

### Start Local Development Services

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/quick_start.md

Start the Docker services for local development.

```bash
docker compose -f local.yml up
```

--------------------------------

### Public Document Mention Setup (Python)

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/permissioning/consolidated_permissioning_guide.md

Sets up a public document for testing mention scenarios. This code snippet is part of a larger example demonstrating permissioning for public resources.

```python
# Setup
public_doc = Document.objects.create(
    title="Public Contract Template",
    is_public=True,
    creator=owner
)


```

--------------------------------

### Environment Variables for Pipeline Setup

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

Example environment variables to set for configuring pipeline components like PDF parsers and multimodal embedders before the first migration.

```bash
# Parser selection (optional - defaults to docling)
PDF_PARSER=docling  # Options: docling, llamaparse

# LlamaParse (if using llamaparse parser)
LLAMAPARSE_API_KEY=your-api-key-here

# Multimodal embedder (if using)
MULTIMODAL_EMBEDDER_HOST=multimodal-embedder
MULTIMODAL_EMBEDDER_PORT=8000
MULTIMODAL_EMBEDDER_VECTOR_SIZE=768
```

--------------------------------

### Start Backend Services Separately

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/quick_start.md

Run this command to start only the backend services, preparing for separate frontend deployment.

```bash
$ docker compose -f local.yml up
```

--------------------------------

### Migrate from VCR to TestModel for Testing

Source: https://github.com/open-source-legal/opencontracts/blob/main/opencontractserver/tests/TESTING_PATTERNS.md

Example demonstrating the previous VCR approach for testing, highlighting its complex setup for ID normalization. This serves as a reference for migration to the TestModel pattern.

```python
@vcr.use_cassette(
    "fixtures/vcr_cassettes/pydantic_ai_ask_document_tool.yaml",
    record_mode="once",
    filter_headers=["authorization", "x-api-key"],
    match_on=["method", "scheme", "host", "port", "path", "query", "body"],
)
async def test_with_vcr(self):
    # Complex VCR setup with ID normalization
    my_vcr = create_vcr_with_id_normalization(
        "pydantic_ai_ask_document_tool.yaml",
        {**self.doc_id_mapping, **self.corpus_id_mapping},
    )

    with my_vcr.use_cassette("pydantic_ai_ask_document_tool.yaml"):
        agent = await PydanticAICorpusAgent.create(...)
        # ... test code
```

--------------------------------

### Start Production Services

Source: https://github.com/open-source-legal/opencontracts/blob/main/README.md

Start the production services in detached mode after applying migrations.

```bash
# Start services
docker compose -f production.yml up -d
```

--------------------------------

### Start OpenContracts with Fullstack Profile

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/quick_start.md

Use this command to start all OpenContracts services, including the frontend, when no frontend development is planned.

```bash
$ docker compose -f local.yml --profile fullstack up
```

--------------------------------

### Start Document Analysis Mutation

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/analyzer_framework/frontend.md

Example of how to use the START_ANALYSIS GraphQL mutation to initiate a document analysis. Ensure you have the necessary documentId, analyzerId, and optionally corpusId and analysisInputData.

```typescript
const [startDocumentAnalysis] = useMutation<StartAnalysisOutput, StartAnalysisInput>(START_ANALYSIS);

const handleStartAnalysis = async () => {
  const result = await startDocumentAnalysis({
    variables: {
      documentId: "doc-123",
      analyzerId: "analyzer-456",
      corpusId: "corpus-789",
      analysisInputData: { customParam: "value" }
    },
  });
};
```

--------------------------------

### Restore Database Backup (PostgreSQL Example)

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/migrations/v3_upgrade_guide.md

Example command for restoring a PostgreSQL database from a backup file. This is a critical step in the rollback process.

```bash
# Example for PostgreSQL
pg_restore -h localhost -U opencontracts -d opencontracts backup.dump
```

--------------------------------

### Start Production Test Stack

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/development/test-suite.md

Starts all services for the production test stack, excluding nlm-ingestor for faster startup. Ensure services are ready by checking their status.

```bash
# Start all services (nlm-ingestor has been removed for faster startup)
docker compose -f production.yml -f compose/test-production.yml up -d

# Wait for services to be ready (Django takes 1-2 minutes)
docker compose -f production.yml -f compose/test-production.yml ps
```

--------------------------------

### First-Time Setup: Discover Components

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

The first step in setting up the pipeline is to discover available components and their configuration requirements. This command lists components and their settings.

```bash
# 1. Discover what components exist and what they need
docker compose -f local.yml run django python manage.py migrate_pipeline_settings --list-components
```

--------------------------------

### List Completed Uploads

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/worker_uploads/walkthrough.md

This example shows how to filter uploads to list only those with a 'COMPLETED' status using a GET request.

```http
GET /api/worker-uploads/documents/list/?status=COMPLETED
```

--------------------------------

### Serve MkDocs Locally

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/development/documentation.md

Starts a local development server for live previewing documentation changes.

```bash
mkdocs serve
```

--------------------------------

### First-Time Setup: Run Django Migrations

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

Run Django migrations to create the PipelineSettings singleton model, which stores pipeline configurations.

```bash
# 3. Run migrations - creates PipelineSettings singleton from Django settings
docker compose -f local.yml run django python manage.py migrate
```

--------------------------------

### TypeScript Usage for Getting Documents

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/features/corpus_folders_api_reference.md

Examples demonstrating how to use the `useQuery` hook with the `GET_DOCUMENTS` query to fetch root documents or documents from a specific folder.

```typescript
// Get root documents
const { data } = useQuery(GET_DOCUMENTS, {
  variables: {
    corpusId: selectedCorpusId,
    inFolderId: "__root__"
  }
});

// Get documents in specific folder
const { data } = useQuery(GET_DOCUMENTS, {
  variables: {
    corpusId: selectedCorpusId,
    inFolderId: selectedFolderId
  }
});
```

--------------------------------

### List All Components and Settings Schemas

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

Use this command to see all available components and their respective settings schemas. This is useful for understanding the configuration structure.

```bash
python manage.py migrate_pipeline_settings --list-components
```

--------------------------------

### First-Time Setup: Verify Settings

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

Verify that all pipeline components have their required settings configured. This command checks for completeness.

```bash
# 5. Verify all components have required settings
docker compose -f local.yml run django python manage.py migrate_pipeline_settings --verify
```

--------------------------------

### Add Start Date Metadata Column

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/metadata/metadata_api_examples.md

Adds a required 'Start Date' column of type 'DATE' to a corpus. This is used to record the effective start date of a contract.

```graphql
# Add start date field
mutation AddStartDate {
  createMetadataColumn(
    corpusId: "Q29ycHVzVHlwZTo3ODk=",
    name: "Start Date",
    dataType: "DATE",
    helpText: "Contract effective start date",
    validationConfig: {
      required: true
    }
  ) {
    ok
    obj {
      id
      name
    }
  }
}
```

--------------------------------

### Clone and Set Up Development Environment

Source: https://github.com/open-source-legal/opencontracts/blob/main/README.md

Clone the repository and copy sample environment files to set up a local development environment. This includes backend Django and frontend environment configurations.

```bash
git clone https://github.com/Open-Source-Legal/OpenContracts.git
cd OpenContracts

# Copy sample environment files
mkdir -p .envs/.local
cp ./docs/sample_env_files/backend/local/.django ./.envs/.local/.django
cp ./docs/sample_env_files/backend/local/.postgres ./.envs/.local/.postgres
cp ./docs/sample_env_files/frontend/local/django.auth.env ./.envs/.local/.frontend

# Build and start all services (including frontend)
docker compose -f local.yml build
docker compose -f local.yml --profile fullstack up
```

--------------------------------

### Start Production Services

Source: https://github.com/open-source-legal/opencontracts/blob/main/CLAUDE.md

Launch the main services for the application in a production environment after migrations have been applied.

```bash
docker compose -f production.yml up
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/open-source-legal/opencontracts/blob/main/CLAUDE.md

Compile and bundle the frontend application for production deployment.

```bash
cd frontend
yarn build
```

--------------------------------

### Preview Production Frontend Build

Source: https://github.com/open-source-legal/opencontracts/blob/main/CLAUDE.md

Locally serve the production-ready build of the frontend application for testing.

```bash
cd frontend
yarn serve
```

--------------------------------

### Install Worker Dependencies

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/social-media-previews.md

Command to install project dependencies for the Cloudflare Worker after navigating to its directory.

```bash
cd cloudflare-og-worker
npm install
```

--------------------------------

### GraphQL API - Start Extract Mutation

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/extract_and_retrieval/api_reference.md

Mutation to start an extract process for a given extract ID.

```APIDOC
## GraphQL API - Start Extract Mutation

### `StartExtract`

Starts the extract process for a specified extract.

#### Parameters
- **extractId** (ID!) - Required - The ID of the extract to start.

#### Returns
- **ok** (Boolean) - Indicates if the operation was successful.
- **message** (String) - A message describing the result.
- **objId** (ID) - The ID of the started extract.

```graphql
mutation StartExtract($extractId: ID!) {
    startExtract(extractId: $extractId) {
        ok
        message
        objId
    }
}
```
```

--------------------------------

### Decorator Metadata Handling Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/walkthrough/advanced/register-doc-analyzer.md

Example of decorator handling metadata, storing it typically with the Analysis object.

```python
# Metadata Handling: The metadata is stored, typically with the `Analysis` object, for future reference.
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/open-source-legal/opencontracts/blob/main/CLAUDE.md

Launch the React development server, which proxies requests to the Django backend running on port 8000.

```bash
cd frontend
yarn start
```

--------------------------------

### List All Pipeline Components

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

Use this command to list all available pipeline components and their required settings. This helps in understanding what configurations are needed before setup.

```bash
# List all components and their settings
docker compose -f local.yml run django python manage.py migrate_pipeline_settings --list-components
```

--------------------------------

### Decorator Task Status Update Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/walkthrough/advanced/register-doc-analyzer.md

Example of decorator updating task status based on the task_pass value.

```python
# Task Status Update: Based on the `task_pass` value, the status of the analysis is updated.
```

--------------------------------

### First-Time Setup: Migrate Pipeline Settings

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/pipelines/pipeline_configuration.md

Migrate component settings from environment variables into the database. This command populates the PipelineSettings model.

```bash
# 4. Migrate component settings from environment variables to database
docker compose -f local.yml run django python manage.py migrate_pipeline_settings
```

--------------------------------

### Decorator Validation Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/walkthrough/advanced/register-doc-analyzer.md

Example of decorator validation checking for a tuple of length 4 with correct element types.

```python
# Validation: The decorator first checks that the return value is a tuple of length 4 and that each element has the
# correct type.
```

--------------------------------

### Create and Use SimpleLLMClient

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/llms/README.md

Demonstrates how to create a lightweight LLM client for OpenAI and make an asynchronous chat completion request.

```python
from opencontractserver.llms.client import create_client, Provider

client = create_client(provider=Provider.OPENAI, model="gpt-4o-mini")
response = await client.achat([
    {"role": "user", "content": "Summarize this text..."}
])
print(response.content)
```

--------------------------------

### Add Moderator Example Payload

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/commenting_system/graphql_api.md

An example JSON payload for the AddModerator mutation, specifying the corpus, user, and permissions.

```json
{
  "corpusId": "Q29ycHVzVHlwZTox",
  "userId": "VXNlclR5cGU6NQ==",
  "permissions": ["lock_threads", "pin_threads"]
}
```

--------------------------------

### Creating an Agent with CoreTool Objects

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/llms/README.md

This example shows an alternative method for creating an agent by passing a list of pre-configured CoreTool instances, obtained from a convenience function. This approach is useful for managing and reusing tool configurations.

```python
# Or use CoreTool objects directly (e.g., from the convenience function)
# create_document_tools() provides a list of pre-configured CoreTool instances.
document_tools = create_document_tools()
agent = await agents.for_document(document=123, corpus=1, tools=document_tools) # Use actual document/corpus IDs
```

--------------------------------

### Example Vote Message Payloads

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/commenting_system/graphql_api.md

Examples of JSON payloads for the `voteMessage` mutation, demonstrating how to upvote and then change a vote to downvote.

```json
# Upvote a message
{
  "messageId": "Q2hhdE1lc3NhZ2VUeXBlOjEwMA==",
  "voteType": "upvote"
}

# Change to downvote
{
  "messageId": "Q2hhdE1lc3NhZ2VUeXBlOjEwMA==",
  "voteType": "downvote"
}
```

--------------------------------

### Tool Filtering Logic Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/permissioning/consolidated_permissioning_guide.md

Illustrates the tool filtering process that occurs before agent initialization, ensuring tools are filtered based on user permissions.

```python
# Lines 178-210 in agent_factory.py
```

--------------------------------

### Signup Form Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/guides/building-document-imports-with-caml.md

Provides a signup form for users to subscribe to updates. Includes a title, button text, and a brief description.

```markdown
:::: signup
title: Stay Informed
button: Subscribe to Updates
Get weekly regulatory updates delivered to your inbox.
::::
```

--------------------------------

### Selection Deep-Link Examples

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/deep-linking.md

Examples of deep links used to pre-select annotations or filter content within a corpus or document.

```bash
# Document with annotations selected
/d/john/contracts/deal?ann=QW5ub3RhdGlvbjox,QW5ub3RhdGlvbjoy

# Corpus filtered by analysis
/c/john/contracts?analysis=QW5hbHlzaXM6NDU2

# Document with thread open in sidebar
/d/john/contracts/deal?thread=Q29udmVyc2F0aW9uOjEyMw
```

--------------------------------

### Start Celery Beat Scheduler

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/telemetry/Backend.md

Celery Beat must be running for periodic tasks to execute. Start the scheduler with the specified command.

```bash
celery -A config.celery_app beat --loglevel=info
```

--------------------------------

### Initialize and Search CoreAnnotationVectorStore

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/extract_and_retrieval/vector_stores.md

Demonstrates initializing the framework-agnostic CoreAnnotationVectorStore with filtering parameters and executing a vector search query with specific filters. Use this for core business logic independent of AI frameworks.

```python
from opencontractserver.llms.vector_stores.core_vector_stores import (
    CoreAnnotationVectorStore,
    VectorSearchQuery,
    VectorSearchResult,
)

# Initialize core store with filtering parameters
core_store = CoreAnnotationVectorStore(
    corpus_id=123,
    user_id=456,
    embedder_path="sentence-transformers/all-MiniLM-L6-v2",
    embed_dim=384,
)

# Create framework-agnostic query
query = VectorSearchQuery(
    query_text="What are the key findings?",
    similarity_top_k=10,
    filters={"label": "conclusion"}
)

# Execute search
results = core_store.search(query)

# Access results
for result in results:
    annotation = result.annotation  # Django Annotation model
    score = result.similarity_score  # Similarity score (0.0-1.0)
```

--------------------------------

### Example: User's Manual Annotations

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/permissioning/consolidated_permissioning_guide.md

This example demonstrates querying for manual annotations by omitting the `analysis_id`. It will not include analysis-linked annotations.

```graphql
# Query without analysis_id - sees manual annotations only
query {
    document(id: "DocumentID") {
        allAnnotations(corpusId: "CorpusID") {
            id
            rawText
            # Will NOT include analysis-linked annotations
            # even if you created them or have permission
        }
    }
}
```

--------------------------------

### Adapter Class for New Frameworks

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/extract_and_retrieval/vector_stores.md

Example of creating an adapter class to integrate a new agent framework with the core vector store.

```python
class MyFrameworkVectorStore:
    def __init__(self, **kwargs):
        self._core_store = CoreAnnotationVectorStore(**kwargs)

    def search(self, framework_query):
        # Convert framework query to VectorSearchQuery
        core_query = self._convert_query(framework_query)

        # Use core store
        results = self._core_store.search(core_query)

        # Convert results back to framework format
        return self._convert_results(results)
```

--------------------------------

### Decorator Error Handling Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/walkthrough/advanced/register-doc-analyzer.md

Example of decorator error handling, marking the task as failed and logging the error if the process fails.

```python
# Error Handling: If any part of this process fails, the decorator handles the error, potentially marking the task
# as failed and logging the error.
```

--------------------------------

### Local Development Environment Variable Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/configuration/frontend-configuration.md

Example of environment variables for local development using Vite. These variables should be prefixed with VITE_.

```env
VITE_USE_AUTH0=true
```

--------------------------------

### Create __init__.py for analyzer/services

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/refactor_plans/2026-05-21-phase3-split-annotations-query-optimizer.md

Initializes the analyzer services package and exposes the AnalysisService.

```python
"""Analyzer service-layer package.

Service Layer Centralization, Phase 3 (issue #1717).
"""

from opencontractserver.analyzer.services.analysis_service import AnalysisService

__all__ = ["AnalysisService"]
```

--------------------------------

### Example Deep Links

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/deep-linking.md

Examples of deep links for accessing shareable state and specific threads within the Open Contracts system.

```plaintext
/d/john/legal-contracts/2024-deal?ann=ann1,ann2&analysis=analysis1&structural=true&boundingBoxes=true&labels=ALWAYS&thread=thread123&folder=folder456
/c/john/contracts/discussions/thread123?message=msg456
```

--------------------------------

### Basic Entity Deep-Link Examples

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/deep-linking.md

Examples of deep links for navigating to different entity types like corpora, documents, and extracts.

```bash
# Corpus page
/c/john/legal-contracts

# Document in corpus
/d/john/legal-contracts/2024-deal

# Standalone document
/d/jane/my-document

# Extract page
/e/john/RXh0cmFjdFR5cGU6MTIz
```

--------------------------------

### Example README with Placeholder URLs

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/upload_methods/corpus_export_import.md

This markdown snippet shows how to use `oc-import://` placeholders for documents and annotations within a README file bundled in a zip archive.

```markdown
# Onboarding

Start with [the master lease](oc-import://document/documents/lease.pdf).
The renewal mechanic lives in [section 4(b)](oc-import://annotation/old-42).
```

--------------------------------

### GraphQL Mutation to Start an Extract

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/extract_and_retrieval/api_reference.md

Initiates the start of an extract process given an extract ID. Returns status, message, and object ID.

```graphql
mutation StartExtract($extractId: ID!) {
    startExtract(extractId: $extractId) {
        ok
        message
        objId
    }
}
```

--------------------------------

### Create Corpus and Docs

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/test_scripts/batch_run_corpus_action.md

Sets up a corpus with three documents and an agent action using Django's shell. This is a prerequisite for triggering the batch run.

```bash
docker compose -f local.yml run --rm django python manage.py shell -c "
from django.contrib.auth import get_user_model
from opencontractserver.corpuses.models import Corpus, CorpusAction, CorpusActionTrigger
from opencontractserver.documents.models import Document, DocumentPath
from opencontractserver.types.enums import PermissionTypes
from opencontractserver.utils.permissioning import set_permissions_for_obj_to_user

User = get_user_model()
owner = User.objects.filter(is_superuser=True).first()
collab, _ = User.objects.get_or_create(username='batch-test-collab', defaults={'email': 'c@test'})

corpus = Corpus.objects.create(title='Batch Test Corpus', creator=owner)
set_permissions_for_obj_to_user(collab, corpus, [PermissionTypes.UPDATE])

for i in range(3):
    doc = Document.objects.create(title=f'Batch Doc {i}', creator=owner)
    DocumentPath.objects.create(
        document=doc, corpus=corpus, path=f'/documents/doc_{doc.pk}',
        version_number=1, is_current=True, is_deleted=False, creator=owner,
    )

action = CorpusAction.objects.create(
    corpus=corpus,
    name='Generate Descriptions',
    trigger=CorpusActionTrigger.ADD_DOCUMENT,
    task_instructions='Read the document and update its description with a one-sentence summary.',
    creator=owner,
)
print(f'corpus={corpus.id} action={action.id} collab={collab.id}')
"
```

--------------------------------

### Decorator Span Label Processing Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/walkthrough/advanced/register-doc-analyzer.md

Example of decorator processing for span labels, creating Annotation objects with detailed span information.

```python
# Span Label Processing: For each span label, it creates an `Annotation` object with detailed information about the
# text span, including its position and content.
```

--------------------------------

### Core APIs: Agents, Embeddings, Vector Stores, Tools

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/llms/README.md

Illustrates the usage of high-level API entry points for creating agents, generating embeddings, interacting with vector stores, and managing tools. Includes an example of creating a custom tool from a function.

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

# Example: Creating a tool using the ToolAPI
def my_custom_function(text: str) -> str:
    """A simple custom tool."""
    return f"Processed: {text}"

custom_tool = tools.from_function(
    func=my_custom_function,
    name="MyCustomTool",
    description="A demonstration tool."
)
# This custom_tool can then be passed to an agent.

# Example: Using AgentAPI convenience methods for structured extraction
result = await agents.get_structured_response_from_document(
    document=123,
    corpus=1,  # Or None for standalone documents
    prompt="Extract key contract terms",
    target_type=ContractTerms,
    framework=AgentFramework.PYDANTIC_AI,
    user_id=456  # Optional
)

# Or extract from an entire corpus
insights = await agents.get_structured_response_from_corpus(
    corpus=1,
    prompt="Analyze patterns across all contracts",
    target_type=CorpusInsights,
    framework=AgentFramework.PYDANTIC_AI
)
```

--------------------------------

### Example: Lock Thread Permission Check in Mutation

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/commenting_system/moderation.md

This example shows how to check for the 'lock_threads' permission within a GraphQL mutation before proceeding with the action.

```python
# In lockThread mutation
if corpus.creator != user:  # Not owner
    moderator = CorpusModerator.objects.get(corpus=corpus, user=user)
    if not moderator.has_permission("lock_threads"):
        return Error(message="You don't have lock permission")
```

--------------------------------

### Build MkDocs Website

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/development/documentation.md

Generates a static HTML website from the Markdown documentation for deployment.

```bash
mkdocs build
```

--------------------------------

### Multimodal Embedder API Response Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/multimodal-embeddings.md

Example JSON response format for multimodal embedder API endpoints, returning 768-dimensional vectors.

```json
{"embeddings": [[0.123, -0.456, ...]]}
```

--------------------------------

### Copy Backend .env Files

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/quick_start.md

Copy the sample backend environment files for Django and PostgreSQL to the local .env directory. These files contain default settings for a basic local deployment.

```bash
cp ./docs/sample_env_files/backend/local/.django ./.envs/.local/.django
cp ./docs/sample_env_files/backend/local/.postgres ./.envs/.local/.postgres
```

--------------------------------

### create_and_setup_analysis Function Signature

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/analyzer_framework/backend.md

Shows the function signature for `create_and_setup_analysis`, responsible for creating and setting up analysis records.

```python
def create_and_setup_analysis(analyzer, user_id, corpus_id=None, doc_ids=None, corpus_action=None):
```

--------------------------------

### Token Reference Example

Source: https://github.com/open-source-legal/opencontracts/blob/main/docs/architecture/pawls-format.md

Example of a JSON object referencing a specific token using its page and token index within the PAWLs structure.

```json
{
  "pageIndex": 0,
  "tokenIndex": 5
}
```