HeropromptBackend

Backend module for HeroPrompt - a code context generator for LLM prompts.

Provides workspace and directory management with file listing, content reading, and search functionality. Uses the filemap module for automatic ignore pattern support (.gitignore, .heroignore).

Quick Start

import incubaid.herolib.ai.heroprompt_backend

fn main() {
    // Create or get a backend instance
    mut backend := heroprompt_backend.new(name: 'default')!

    // Create a workspace
    mut ws := backend.create_workspace(name: 'My Project')!
    println('Created workspace: ${ws.name} (${ws.id})')

    // Add directories to the workspace
    backend.add_dir(
        workspace_id: ws.id
        path: '/path/to/my/project'
    )!

    // List files (respects .gitignore patterns)
    files := backend.list_files(workspace_id: ws.id)!
    for dir_id, file_map in files {
        println('Directory ${dir_id}:')
        for path, _ in file_map.content {
            println('  - ${path}')
        }
    }

    // Search within workspace
    results := backend.search(
        workspace_id: ws.id
        query: 'fn main'
        max_results: 10
    )!
    for result in results {
        println('${result.path}:${result.line_number}: ${result.line}')
    }

    // Generate context for selected files
    context := backend.generate_context(
        workspace_id: ws.id
        file_paths: ['/path/to/my/project/main.v', '/path/to/my/project/lib.v']
    )!
    println(context)
}

API Reference

Workspace Operations

Directory Operations

File Operations

Search & Context

Data Structures

Workspace

pub struct Workspace {
pub mut:
    id         string      // Unique identifier
    name       string      // Display name
    dirs       []Directory // Directories in this workspace
    created_at i64         // Unix timestamp
    updated_at i64         // Unix timestamp
}

Directory

pub struct Directory {
pub mut:
    id         string // Unique identifier
    path       string // Absolute path
    name       string // Display name
    created_at i64    // Unix timestamp
}

SearchResult

pub struct SearchResult {
pub mut:
    path        string // File path
    line_number int    // Line number (1-based)
    line        string // Matching line
    context     string // Context around match
}

Ignore Patterns

The module automatically respects:- .gitignore files (up to repository root)

• .heroignore files
• Default patterns: node_modules/, __pycache__/, .git/, *.pyc, etc.

fn delete(args GetArgs) !

delete removes a HeropromptBackend instance from Redis.

fn exists(args GetArgs) !bool

exists checks if a HeropromptBackend instance exists in Redis.

fn get(args GetArgs) !&HeropromptBackend

get retrieves a HeropromptBackend instance by name.

fn get_file_content(args GetFileContentArgs) !string

get_file_content reads and returns file content.

fn get_file_tree(args GetFileTreeArgs) !FileInfo

get_file_tree returns the file tree structure for a directory.

fn get_files_content(args GetFilesContentArgs) ![]FileContent

get_files_content reads multiple files and returns their content.

fn heroscript_loads(heroscript string) !HeropromptBackend

heroscript_loads parses a HeroScript string into a HeropromptBackend instance.

fn list(args ListArgs) ![]&HeropromptBackend

list returns all HeropromptBackend instances.

fn new(args GetArgs) !&HeropromptBackend

new creates a new HeropromptBackend instance.

fn play(mut plbook PlayBook) !

play executes HeroScript playbook actions.

fn set(o HeropromptBackend) !

set persists a HeropromptBackend instance to Redis.

struct AddDirArgs {
pub mut:
	workspace_id string @[required]
	path         string @[required]
	name         string // Display name (default: directory basename)
}

AddDirArgs specifies options for adding a directory.

struct CreateWorkspaceArgs {
pub mut:
	name string // Display name (default: "Untitled Workspace")
}

CreateWorkspaceArgs specifies options for creating a workspace.

struct DeleteDirArgs {
pub mut:
	workspace_id string @[required]
	dir_id       string @[required]
}

DeleteDirArgs specifies options for deleting a directory.

struct Directory {
pub mut:
	id         string // Unique identifier (UUID)
	path       string // Absolute filesystem path
	name       string // Display name
	created_at i64    // Unix timestamp
}

Directory represents a directory added to a workspace.

struct FileContent {
pub mut:
	path    string
	content string
}

FileContent represents file path and content.

struct FileInfo {
pub mut:
	path     string     // Relative path within directory
	name     string     // File/directory name
	is_dir   bool       // True if directory
	size     i64        // File size in bytes
	children []FileInfo // Children (for directories)
}

FileInfo represents a file or directory in the tree.

struct GenerateContextArgs {
pub mut:
	workspace_id string   @[required]
	file_paths   []string @[required]
}

GenerateContextArgs specifies options for context generation.

struct GetArgs {
pub mut:
	name   string = 'default'
	fromdb bool // Force load from Redis
	create bool // Create if not exists
}

GetArgs specifies options for retrieving a backend instance.

struct GetFileContentArgs {
pub mut:
	path string @[required]
}

GetFileContentArgs specifies options for reading file content.

struct GetFileTreeArgs {
pub mut:
	dir_path  string @[required]
	max_depth int = 10 // Maximum recursion depth
}

GetFileTreeArgs specifies options for building a file tree.

struct GetFilesContentArgs {
pub mut:
	paths []string @[required]
}

GetFilesContentArgs specifies options for reading multiple files.

struct HeropromptBackend {
pub mut:
	name       string = 'default'
	workspaces []Workspace
}

HeropromptBackend manages workspaces and their directories. Use factory functions (new, get) to create instances.

fn (mut self HeropromptBackend) add_dir(args AddDirArgs) !&Directory

add_dir adds a directory to a workspace.

fn (mut self HeropromptBackend) create_workspace(args CreateWorkspaceArgs) !&Workspace

create_workspace creates a new workspace.

fn (mut self HeropromptBackend) delete_dir(args DeleteDirArgs) !

delete_dir removes a directory from a workspace.

fn (mut self HeropromptBackend) delete_workspace(args WorkspaceIdArgs) !

delete_workspace removes a workspace by ID.

fn (self &HeropromptBackend) generate_context(args GenerateContextArgs) !string

generate_context creates a formatted context string from selected files.

fn (self &HeropromptBackend) get_workspace(args WorkspaceIdArgs) !&Workspace

get_workspace returns a workspace by ID.

fn (self &HeropromptBackend) list_dirs(args WorkspaceIdArgs) ![]Directory

list_dirs returns all directories in a workspace.

fn (self &HeropromptBackend) list_files(args ListFilesArgs) !map[string]filemap.FileMap

list_files returns file maps for workspace directories.

fn (self &HeropromptBackend) list_workspaces() []Workspace

list_workspaces returns all workspaces.

fn (mut self HeropromptBackend) reload() !

reload refreshes this instance from Redis.

fn (self &HeropromptBackend) save() !

save persists this instance to Redis.

fn (self &HeropromptBackend) search(args SearchArgs) ![]SearchResult

search searches for a query string within workspace files.

fn (mut self HeropromptBackend) update_workspace(args UpdateWorkspaceArgs) !&Workspace

update_workspace updates workspace properties.

struct ListArgs {
pub mut:
	fromdb bool // Force reload from Redis
}

ListArgs specifies options for listing instances.

struct ListFilesArgs {
pub mut:
	workspace_id string @[required]
	dir_id       string // Filter to specific directory
}

ListFilesArgs specifies options for listing files.

struct SearchArgs {
pub mut:
	workspace_id   string @[required]
	query          string @[required]
	case_sensitive bool
	max_results    int = 100
	context_lines  int = 2
}

SearchArgs specifies options for searching files.

struct SearchResult {
pub mut:
	path        string // File path
	line_number int    // Line number (1-based)
	line        string // Matching line
	context     string // Context around match
}

SearchResult represents a search match.

struct UpdateWorkspaceArgs {
pub mut:
	id   string @[required]
	name string // New name
}

UpdateWorkspaceArgs specifies options for updating a workspace.

struct Workspace {
pub mut:
	id         string      // Unique identifier (UUID)
	name       string      // Display name
	dirs       []Directory // Directories in this workspace
	created_at i64         // Unix timestamp
	updated_at i64         // Unix timestamp
}

Workspace represents a collection of directories for context generation.

struct WorkspaceIdArgs {
pub mut:
	id string @[required]
}

WorkspaceIdArgs specifies a workspace by ID.