Skip to main content

Overview

This page documents the core types, enums, and structures used throughout the nrvna-ai library.
#include <nrvna/types.hpp>

Core Types

JobId

using JobId = std::string;
Opaque identifier for a submitted job. Currently implemented as a string (UUID format), but may evolve to a strong type in future versions. Example:
JobId id = "550e8400-e29b-41d4-a716-446655440000";
std::cout << "Job ID: " << id << std::endl;

Enums

Status

enum class Status : std::uint8_t {
    Queued,   // Job submitted, waiting for processing
    Running,  // Job currently being processed
    Done,     // Job completed successfully
    Failed,   // Job failed with error
    Missing   // Job not found in workspace
};
Represents the lifecycle state of a job.
Queued
Status
Job has been submitted and is waiting in the queue for processing
Running
Status
Job is currently being processed by a worker thread
Done
Status
Job completed successfully and result is available
Failed
Status
Job processing failed and error message is available
Missing
Status
Job ID not found in the workspace (may have been deleted or never existed)
Example:
Status status = flow.status(jobId);

switch (status) {
    case Status::Queued:
        std::cout << "Waiting in queue" << std::endl;
        break;
    case Status::Running:
        std::cout << "Processing..." << std::endl;
        break;
    case Status::Done:
        std::cout << "Complete!" << std::endl;
        break;
    case Status::Failed:
        std::cout << "Failed" << std::endl;
        break;
    case Status::Missing:
        std::cout << "Not found" << std::endl;
        break;
}

JobType

enum class JobType : uint8_t {
    Text = 0,   // Text generation
    Embed = 1,  // Embedding generation
    Vision = 2  // Vision/multimodal processing
};
Specifies the type of inference job.
Text
JobType
Text generation job - generates text response from prompt
Embed
JobType
Embedding generation job - generates vector embedding from text
Vision
JobType
Vision/multimodal job - processes images with text prompt
Example:
// Text generation
auto result1 = work.submit("Hello", JobType::Text);

// Embedding
auto result2 = work.submit("Hello", JobType::Embed);

// Vision (automatically set when using image overload)
auto result3 = work.submit("Describe this", imagePaths);

SubmissionError

enum class SubmissionError : uint8_t {
    None = 0,           // No error occurred
    IoError,            // Filesystem I/O error
    InvalidSize,        // Prompt exceeds maximum size
    InvalidContent,     // Invalid prompt or image content
    WorkspaceError      // Workspace not accessible or invalid
};
Error codes for job submission failures.
None
SubmissionError
No error - submission succeeded
IoError
SubmissionError
Filesystem I/O error occurred (e.g., permission denied, disk full)
InvalidSize
SubmissionError
Prompt size exceeds the configured maximum
InvalidContent
SubmissionError
Prompt is empty, image files are invalid, or content is malformed
WorkspaceError
SubmissionError
Workspace directory is inaccessible or cannot be created
Example:
auto result = work.submit(largePrompt);
if (!result) {
    switch (result.error) {
        case SubmissionError::None:
            // Won't happen when result.ok is false
            break;
        case SubmissionError::IoError:
            std::cerr << "I/O error: " << result.message << std::endl;
            break;
        case SubmissionError::InvalidSize:
            std::cerr << "Prompt too large" << std::endl;
            break;
        case SubmissionError::InvalidContent:
            std::cerr << "Invalid content: " << result.message << std::endl;
            break;
        case SubmissionError::WorkspaceError:
            std::cerr << "Workspace error: " << result.message << std::endl;
            break;
    }
}

Structures

SubmitResult

struct SubmitResult {
    bool ok = false;
    JobId id;
    SubmissionError error = SubmissionError::None;
    std::string message;
    explicit operator bool() const noexcept { return ok; }
};
Result structure returned by Work::submit() methods.
ok
bool
True if submission succeeded, false if it failed
id
JobId
Generated job identifier (only valid when ok is true)
error
SubmissionError
Error code if submission failed (SubmissionError::None if successful)
message
std::string
Human-readable message describing success or failure
Example:
auto result = work.submit("Test prompt");

// Check using operator bool
if (result) {
    std::cout << "Success! Job ID: " << result.id << std::endl;
    std::cout << "Message: " << result.message << std::endl;
} else {
    std::cerr << "Failed with error " << static_cast<int>(result.error) << std::endl;
    std::cerr << "Message: " << result.message << std::endl;
}

// Or check directly
if (result.ok) {
    // ...
}

Job

struct Job {
    JobId id;
    Status status;
    std::string content;
    std::chrono::system_clock::time_point timestamp;
};
Represents a job retrieved from the workspace.
id
JobId
Unique identifier for the job
status
Status
Current lifecycle state of the job
content
std::string
Result content (if Done) or error message (if Failed). Empty for Queued/Running jobs.
timestamp
std::chrono::system_clock::time_point
Job creation or completion timestamp
Example:
auto job = flow.latest();
if (job) {
    std::cout << "Job ID: " << job->id << std::endl;
    
    // Format timestamp
    auto time_t = std::chrono::system_clock::to_time_t(job->timestamp);
    std::cout << "Timestamp: " << std::ctime(&time_t);
    
    // Check status and content
    if (job->status == Status::Done) {
        std::cout << "Result: " << job->content << std::endl;
    } else if (job->status == Status::Failed) {
        std::cerr << "Error: " << job->content << std::endl;
    }
}

Type Conversions

Status to String

std::string statusToString(Status status) {
    switch (status) {
        case Status::Queued:  return "Queued";
        case Status::Running: return "Running";
        case Status::Done:    return "Done";
        case Status::Failed:  return "Failed";
        case Status::Missing: return "Missing";
        default:              return "Unknown";
    }
}

JobType to String

std::string jobTypeToString(JobType type) {
    switch (type) {
        case JobType::Text:   return "Text";
        case JobType::Embed:  return "Embed";
        case JobType::Vision: return "Vision";
        default:              return "Unknown";
    }
}

Notes

  • All enums are strongly typed (enum class)
  • All enums use uint8_t as the underlying type for compact representation
  • JobId is currently a string alias but may become a strong type in the future
  • SubmitResult provides operator bool() for convenient success checking
  • The Job struct uses standard library types for broad compatibility
  • Timestamps use std::chrono::system_clock for portability

Build docs developers (and LLMs) love