NavamAI API Documentation

NavamAI is a Python package that provides a command-line interface for interacting with various AI models and performing tasks such as text generation, image creation, and more. This documentation covers the API for using NavamAI within external projects.

Table of Contents

1. Installation
2. Command-Line Interface
3. Modules
   • claude
   • code
   • configure
   • evaluate
   • gather
   • gemini
   • generate
   • groq
   • images
   • markdown
   • metrics
   • model_text
   • model_vision
   • ollama
   • openai
   • perplexity
   • provider
   • reference
   • utils
   • validation

Installation

To install NavamAI, use pip:

pip install -U navamai

Command-Line Interface

NavamAI provides a command-line interface with various commands. Here's an overview of the available commands:

• run: Processes a selected markdown file and runs the code blocks within it.
• audit: Analyzes the usage of NavamAI over time and generates a report.
• gather: Scrapes content from a webpage and saves it as markdown.
• split: Splits a large text file into smaller chunks.
• trends: Visualizes trends for provider-model combinations.
• test: Tests the specified model configuration.
• init: Initializes NavamAI in the current directory.
• config: Edits the NavamAI configuration.
• id: Identifies the current provider and model for a given section.
• image: Generates an image based on a prompt or template.
• ask: Processes a prompt or template using the configured AI model.
• refer: Processes a document or prompt using a specified section of the configuration.
• intents: Processes intents from a document or template.
• merge: Merges two files based on placeholders.
• validate: Validates generated content using another model.
• vision: Processes an image using vision models and responds based on a prompt.

For detailed usage of each command, please refer to the CLI documentation or use the --help option with each command.

Modules

claude

The claude module provides a Claude class that interacts with the Anthropic API for text and vision tasks.

Class: Claude

class Claude(Provider):
    def __init__(self):
        # Initialize the Claude provider
    
    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt
    
    def stream_vision_response(self, image_data: bytes, prompt: str, media_type: str = None) -> Generator[str, None, None]:
        # Stream a response for a given image and text prompt

code

The code module provides functionality for processing markdown files and running code blocks.

Functions:

def process_markdown_file(file_path: str, app_folder: str):
    # Process a markdown file, extract code blocks, and run them

configure

The configure module handles configuration management for NavamAI.

Functions:

def load_config(section: Optional[str] = None) -> Dict[str, Any]:
    # Load the configuration from navamai.yml

def has_vision_capability(model: str) -> bool:
    # Check if a model has vision capabilities

def save_config(config: Dict[str, Any]):
    # Save the configuration to navamai.yml

def edit_config(keys: List[str], value: Any):
    # Edit a specific configuration value

def get_model_mapping() -> Dict[str, str]:
    # Get the model mapping from the configuration

def resolve_model(model: str) -> str:
    # Resolve a model name to its actual identifier

evaluate

The evaluate module provides functionality for evaluating model configurations.

Functions:

def by_model_config(model_config: str):
    # Evaluate the specified model configuration across all compatible providers and models

gather

The gather module provides functionality for scraping web articles and saving them as markdown files.

Functions:

def article(url: str) -> Optional[str]:
    # Scrape an article from the given URL and save it as a markdown file
    # Returns the path of the saved file or None if scraping failed

gemini

The gemini module provides a Gemini class that interacts with the Google Generative AI API for text and vision tasks.

Class: Gemini

class Gemini(Provider):
    def __init__(self):
        # Initialize the Gemini provider
    
    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt
    
    def stream_vision_response(self, image_data: bytes, prompt: str, media_type: str) -> Generator[str, None, None]:
        # Stream a response for a given image and text prompt

generate

The generate module provides functionality for generating images using various AI providers.

Functions:

def image(prompt: Optional[str], template: Optional[str]) -> Dict[str, Any]:
    # Generate an image based on a prompt or template
    # Returns a dictionary with information about the generated image

def _generate_image_with_progress(provider_instance: Provider, prompt: str, duration: int) -> str:
    # Generate an image with a progress bar
    # Returns the path of the generated image file

groq

The groq module provides a Groq class that interacts with the Groq API for text-based tasks.

Class: Groq

class Groq(Provider):
    def __init__(self):
        # Initialize the Groq provider
    
    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt
    
    def stream_vision_response(self, image_data: bytes, prompt: str, media_type: str) -> Generator[str, None, None]:
        # Raises NotImplementedError as Groq doesn't support vision-based responses

images

The images module provides utility functions for handling images in NavamAI.

Functions:

def display_image(image_path: str):
    # Display an image in the terminal (works best in VS Code Terminal)

def capture_image() -> bytes:
    # Capture an image from the camera and return it as bytes

def resize_image(image_data: bytes, max_size: int = 5 * 1024 * 1024) -> bytes:
    # Resize an image to ensure it's under a specified size (default 5MB)
    # Returns the resized image as bytes

markdown

The markdown module provides utility functions for working with markdown files and text processing.

Functions:

def split_text_by_tokens(file_path: str, model: str = "gpt-3.5-turbo") -> int:
    # Split a text file into chunks based on token count
    # Returns the number of chunks created

def extract_variables(template: str) -> List[str]:
    # Extract variables enclosed in double curly braces from a template string

def list_files(directory: str, page: int = 1, files_per_page: int = 10, extensions: Optional[List[str]] = None) -> Tuple[List[str], int]:
    # List files in a directory with pagination

def count_tokens(file_path: str) -> int:
    # Count the number of tokens in a file

def intent_select_paginate(sections: List[Tuple[str, str]], page: int = 1, intents_per_page: int = 10) -> Optional[Tuple[str, str]]:
    # Display a paginated list of intents for selection

def file_select_paginate(directory: str, show_tokens: bool = False, section: Optional[str] = None, extensions: Optional[List[str]] = None) -> Optional[str]:
    # Display a paginated list of files for selection

def merge_docs(source_path: str, dest_suffix: str = "expanded", merge_suffix: str = "merged", placeholder: str = "[merge here]", prompt_prefix: str = "> Prompt:"):
    # Merge two markdown documents based on placeholders

def diff(content1: str, content2: str) -> float:
    # Calculate the difference percentage between two content strings

def parse_markdown_sections(content: str) -> List[Tuple[str, str]]:
    # Parse markdown content into sections (title and prompt)

def update_markdown_with_response(filename: str, title: str, response_filename: str):
    # Update a markdown file with an Obsidian-flavored embed for a response

metrics

The metrics module provides functions for tracking and analyzing metrics related to model performance.

Functions:

def count_tokens(text: str) -> int:
    # Count the number of tokens in the given text

def save_test_summary(provider: str, model: str, model_config: str, prompt: str, status: str, details: str, response_time: float, token_count: int):
    # Save a test summary to a YAML file

def read_yaml_files(directory: str = "Metrics") -> Dict[str, Any]:
    # Read test summary YAML files from a directory

def process_data(data: Dict[str, Any], days: int = 7) -> Dict[Tuple[str, str, str], Dict[str, List[Any]]]:
    # Process test summary data for trend analysis

def display_trends(processed_data: Dict[Tuple[str, str, str], Dict[str, List[Any]]]):
    # Display trends for response times and token counts

model_text

The model_text module handles text-based model interactions.

Functions:

def process(prompt: Optional[str], template: Optional[str]) -> Dict[str, Any]:
    # Process a text prompt or template using the configured AI model
    # Returns a dictionary with information about the processed prompt and response

model_vision

The model_vision module handles vision-based model interactions.

Functions:

def process(path: Optional[str], url: Optional[str], camera: bool, display: bool, prompt: Optional[str]) -> Dict[str, Any]:
    # Process an image using vision models and respond based on a prompt
    # Returns a dictionary with information about the processed image and response

ollama

The ollama module provides an Ollama class for interacting with locally hosted Ollama models.

Class: Ollama

class Ollama(Provider):
    def __init__(self):
        # Initialize the Ollama provider
    
    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt
    
    def stream_vision_response(self, image_data: bytes, prompt: str, media_type: str) -> Generator[str, None, None]:
        # Stream a response for a given image and text prompt

Note: The Ollama provider does not support WebP image format for vision tasks.

openai

The openai module provides an Openai class for interacting with OpenAI's API for text and image generation tasks.

Class: Openai

class Openai(Provider):
    def __init__(self):
        # Initialize the OpenAI provider

    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt

    def stream_vision_response(self, image_data: bytes, prompt: str, media_type: str) -> Generator[str, None, None]:
        # Stream a response for a given image and text prompt

    def generate_image(self, prompt: str) -> str:
        # Generate an image based on a text prompt
        # Returns the filepath of the generated image

    def save_image_response(self, prompt: str, image_data: bytes) -> str:
        # Save a generated image to a file
        # Returns the filepath of the saved image

perplexity

The perplexity module provides a Perplexity class for interacting with the Perplexity AI API for text-based tasks.

Class: Perplexity

class Perplexity(Provider):
    def __init__(self):
        # Initialize the Perplexity provider

    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt

    def stream_vision_response(self, image_data: bytes, prompt: str) -> Generator[str, None, None]:
        # Not implemented for Perplexity (raises NotImplementedError)

provider

The provider module defines an abstract Provider class that serves as a base for all AI provider implementations.

Class: Provider

class Provider(ABC):
    def __init__(self):
        # Initialize the provider

    @abstractmethod
    def create_request_data(self, prompt: str) -> dict:
        # Create request data for the API call

    @abstractmethod
    def stream_response(self, prompt: str) -> Generator[str, None, None]:
        # Stream a response for a given text prompt

    @abstractmethod
    def stream_vision_response(self, image_data: bytes, prompt: str, media_type: Optional[str] = None) -> Generator[str, None, None]:
        # Stream a response for a given image and text prompt

    def set_model_config(self, model_config: str):
        # Set the model configuration

    def ask(self, prompt: str, title: Optional[str] = None) -> Optional[str]:
        # Process a text prompt and optionally save the response

    def vision(self, image_data: bytes, prompt: str, title: Optional[str] = None):
        # Process an image prompt

    def save_response(self, prompt: str, response: str, title: Optional[str] = None) -> str:
        # Save a response to a file

    def get_model_info(self) -> str:
        # Get information about the current model

    def resolve_model(self, model: str) -> str:
        # Resolve the actual model name from the configuration

reference

The reference module provides functionality for processing documents and prompts using specific configurations.

Functions:

def process(section: str, document: Optional[str] = None, prompt: Optional[str] = None) -> Dict[str, Any]:
    # Process a document or prompt using a specified configuration section
    # Returns a dictionary with information about the processed document and response

def _document_prompt(config_section: str, document: Optional[str] = None, prompt: Optional[str] = None) -> Tuple[str, Optional[str], Optional[str]]:
    # Internal function to handle document selection and prompt processing

utils

The utils module provides utility functions and decorators for the NavamAI package.

Functions:

def trail(f):
    # Decorator to log command executions and their results

def get_provider_instance(provider: str) -> Provider:
    # Get an instance of the specified AI provider

validation

The validation module provides functionality for validating generated content using another model.

Functions:

def validate(document: Optional[str] = None) -> Dict[str, Any]:
    # Validate generated content using another model
    # Returns a dictionary with information about the validation process