Journey: Create and Register a Prompt

Goal: Create a reusable prompt template for LLM operations in plugins

Prerequisites:

Valid JWT token for API authentication
Understanding of your use case (classification, extraction, etc.)

Overview

Prompts are reusable LLM instruction templates stored in the system. Plugins reference prompts by ID to perform classification, extraction, and other AI-powered operations.

Why use prompts?

Centralized management of LLM instructions
Version control through updates
Scope-based sharing (global, tenant, user)
Reusable across multiple plugins

Step 1: Write Your Prompt Template

Create a .txt file with your LLM instructions. Use clear, structured prompts.

Example: invoice_classification.txt

You are a document classification expert. Analyze the provided document and determine if it is an invoice.

Instructions:
1. Look for invoice-specific elements: invoice number, line items, totals, payment terms
2. Consider the document structure and formatting
3. Evaluate confidence based on how many invoice elements are present

Respond in JSON format:
{
  "is_invoice": true/false,
  "confidence": 0.0-1.0,
  "reasoning": "Brief explanation"
}

Tips:

Be specific about the expected output format
Include examples if the task is complex
Use JSON output format for easy parsing in plugins

Step 2: Choose Access Scope

Scope	Who Can Access	Use When
`user`	Only you	Personal/experimental prompts
`tenant`	All users in your organization	Team-shared prompts (default)
`global`	All users across all tenants	Platform-wide standard prompts (admin only)

Step 3: Register Prompt via API

Request:

POST /prompts
Authorization: Bearer <your-jwt-token>
Content-Type: multipart/form-data

Query Parameters:
- name: "Invoice Classification" (required)
- description: "Classifies documents as invoices" (optional)
- scope: "tenant" (optional, default: "tenant")

Form Fields:
- prompt_file: invoice_classification.txt

Using curl:

curl -X POST "https://api.bizsupply.com/prompts?name=Invoice%20Classification&description=Classifies%20documents%20as%20invoices&scope=tenant" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "prompt_file=@invoice_classification.txt"

Response:

{
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000"
}

Save the prompt_id - you'll need it when configuring plugins!

Step 4: Verify Prompt Registration

Request:

GET /prompts
Authorization: Bearer <your-jwt-token>

Response:

{
  "count": 1,
  "prompts": [
    {
      "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Invoice Classification",
      "description": "Classifies documents as invoices",
      "scope": "tenant",
      "created_at": "2025-01-12T10:00:00Z",
      "updated_at": "2025-01-12T10:00:00Z"
    }
  ]
}

Step 5: Use Prompt in a Plugin

When creating or configuring a plugin, reference the prompt by ID:

In plugin code (class attributes):

class MyClassifierPlugin(ClassificationPlugin):
    """Classifies documents using prompts."""

    configurable_parameters = [
        {
            "parameter_name": "classification_prompt",
            "parameter_type": "str",
            "default_value": None,
            "description": "Prompt ID for classification instructions",
        },
    ]

    async def execute(self, context: PluginContext):
        # Get prompt ID from configuration
        prompt_id = context.plugin_configs.get("classification_prompt")

        # Load the prompt template
        prompt_template = await self.get_prompt(prompt_id)

        # Use in LLM call
        response = await self.prompt_llm(prompt=prompt_template, ...)

When running a pipeline, pass the prompt ID as a plugin parameter:

{
  "plugin_id": "your-plugin-id",
  "plugin_configs": {
    "classification_prompt": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Managing Prompts

Get Prompt Details

GET /prompts/{prompt_id}
Authorization: Bearer <your-jwt-token>

Update Prompt

PATCH /prompts/{prompt_id}
Authorization: Bearer <your-jwt-token>
Content-Type: multipart/form-data

Query Parameters (all optional):
- name: "New Name"
- description: "New description"

Form Fields (optional):
- prompt_file: updated_prompt.txt

Delete Prompt

DELETE /prompts/{prompt_id}
Authorization: Bearer <your-jwt-token>

Common Prompt Patterns

Classification Prompt

Classify this document into one of the following categories: {categories}

Document: {document_content}

Respond with JSON: {"category": "...", "confidence": 0.0-1.0}

Entity Extraction Prompt

Extract the following entities from the document:
- Vendor name
- Invoice date
- Total amount
- Line items

Document: {document_content}

Respond with JSON containing the extracted values.

Contract Analysis Prompt

Analyze this contract and extract:
1. Parties involved
2. Effective date
3. Termination clauses
4. Key obligations

Document: {document_content}

Respond with structured JSON.

Next Steps

Create a plugin: Follow Create a Plugin to build a plugin that uses your prompt
Run a pipeline: Follow Use Plugins to execute plugins with your prompt
Create ontology: Follow Create an Ontology for structured extraction schemas