Documentation Index

‍⚠️ EDUCATIONAL USE ONLY - This software is licensed for educational and learning purposes only. Not for production, commercial, or application deployment. See [LICENSE](LICENSE) and NOTICE.md for complete details.

This file provides additional documentation for the Prompt Workbench Core library.

Overview

Prompt Workbench Core is a C static library designed for testing and evaluating prompts against OpenAI-compatible APIs. It provides:

• API Client: Make requests to OpenAI-compatible endpoints
• Database Layer: SQLite-based storage for test suites and user prompts
• Cross-Platform: Works on Linux, macOS, and Windows
• Static Linking: All dependencies bundled into a single static library

Architecture

Components

1. API Client (api-client.h/api-client.c)
   • HTTP client using libcurl
   • JSON parsing with cJSON
   • Automatic extraction of chat completion responses
2. Database (db.h/db.c)
   • SQLite-based persistence
   • Full CRUD operations for test suites and user prompts
   • Foreign key constraints with CASCADE deletes
3. Library Interface (library.h/library.c)
   • Main library entry point
   • Version information

Data Model

Test Suites

A test suite represents a collection of prompts to test with specific configuration:

• id: Unique identifier
• title: Human-readable name
• description: Optional description
• system_prompt: System message for the AI
• model: Model identifier (e.g., "gpt-4")

User Prompts

User prompts are questions or inputs to test:

• id: Unique identifier
• prompt: The actual prompt text
• test_suite_id: Foreign key to parent test suite

Usage Examples

Creating a Test Suite

#include "db.h"
 
int main() {
    db_init("my_tests.db");
    
    int suite_id = db_create_test_suite(
        "Code Review Assistant",
        "Tests for code review prompts",
        "You are an expert code reviewer",
        "gpt-4"
    );
    
    db_create_user_prompt("Review this function for bugs", suite_id);
    db_create_user_prompt("Suggest performance improvements", suite_id);
    
    db_close();
    return 0;
}

Making API Calls

#include "api-client.h"
 
int main() {
    char* response = api_ask(
        "https://api.openai.com/v1/chat/completions",
        getenv("OPENAI_API_KEY"),
        "gpt-4",
        "You are a helpful assistant",
        "What is the capital of France?"
    );
    
    if (response) {
        printf("Answer: %s\n", response);
        api_ask_free(response);
    }
    
    return 0;
}

Reading Test Data

#include "db.h"
 
int main() {
    db_init("my_tests.db");
    
    // Get all test suites
    int count;
    test_suite_t** suites = db_get_all_test_suites(&count);
    
    for (int i = 0; i < count; i++) {
        printf("Suite: %s\n", suites[i]->title);
        
        // Get prompts for this suite
        int prompt_count;
        user_prompt_t** prompts = db_get_user_prompts_by_suite(
            suites[i]->id, &prompt_count
        );
        
        for (int j = 0; j < prompt_count; j++) {
            printf("  - %s\n", prompts[j]->prompt);
        }
        
        db_free_user_prompts(prompts, prompt_count);
    }
    
    db_free_test_suites(suites, count);
    db_close();
    return 0;
}

Memory Management

All functions that return allocated memory require the caller to free it:

• api_ask() → api_ask_free()
• db_get_test_suite() → db_free_test_suite()
• db_get_all_test_suites() → db_free_test_suites()
• db_get_user_prompt() → db_free_user_prompt()
• db_get_user_prompts_by_suite() → db_free_user_prompts()
• db_get_all_user_prompts() → db_free_user_prompts()

Error Handling

Functions return specific values to indicate errors:

• Functions returning int: Return -1 on error, or a positive ID/0 on success
• Functions returning pointers: Return NULL on error
• Always check return values before using the result

Thread Safety

• Database operations are not thread-safe. Use external synchronization.
• API client operations can be called from multiple threads (libcurl is thread-safe when used correctly).

Platform Notes

Linux

• Requires pthread and math libraries (linked automatically)
• Build with GCC or Clang

macOS

• Build with Clang
• May require Xcode Command Line Tools

Windows

• Build with MSVC or MinGW
• Link against Ws2_32.lib and Crypt32.lib for curl support

Building from Source

See the main README.md for build instructions.

Contributing

When contributing, ensure:

1. All unit tests pass
2. New functionality includes tests
3. Code follows the existing style
4. Documentation is updated

License

See LICENSE file for license information.