nomyo/doc/api-reference.md

API Reference

SecureChatCompletion Class

The SecureChatCompletion class is the main entry point for using the NOMYO secure client. It provides the same interface as OpenAI's ChatCompletion API with end-to-end encryption.

Constructor

SecureChatCompletion(
    base_url: str = "https://api.nomyo.ai",
    allow_http: bool = False,
    api_key: Optional[str] = None,
    secure_memory: bool = True,
    max_retries: int = 2
)

Parameters:

• base_url (str): Base URL of the NOMYO Router (must use HTTPS for production)
• allow_http (bool): Allow HTTP connections (ONLY for local development, never in production)
• api_key (Optional[str]): Optional API key for bearer authentication
• secure_memory (bool): Enable secure memory protection (default: True)
• max_retries (int): Number of retries on retryable errors (429, 500, 502, 503, 504, network errors). Uses exponential backoff. Default: 2

Methods

create(model, messages, **kwargs)

Creates a new chat completion for the provided messages and parameters.

Parameters:

• model (str): The model to use for the chat completion
• messages (List[Dict]): A list of message objects. Each message has a role ("system", "user", or "assistant") and content
• **kwargs: Additional parameters that can be passed to the API

Supported OpenAI Parameters:

• temperature (float): Sampling temperature (0-2)
• max_tokens (int): Maximum tokens to generate
• top_p (float): Nucleus sampling
• frequency_penalty (float): Frequency penalty
• presence_penalty (float): Presence penalty
• stop (Union[str, List[str]]): Stop sequences
• n (int): Number of completions
• stream (bool): Streaming always = False to minimize de-/encryption overhead
• tools (List): Tool definitions
• tool_choice (str): Tool selection strategy
• user (str): User identifier
• security_tier (str): Security level ("standard", "high", or "maximum")

Returns: A dictionary containing the chat completion response with the following structure:

{
    "id": str,
    "object": "chat.completion",
    "created": int,
    "model": str,
    "choices": [
        {
            "index": int,
            "message": {
                "role": str,
                "content": str,
                "tool_calls": List[Dict]  # if tools were used
            },
            "finish_reason": str
        }
    ],
    "usage": {
        "prompt_tokens": int,
        "completion_tokens": int,
        "total_tokens": int
    },
    "_metadata": {
        "payload_id": str,
        "processed_at": int,          # Unix timestamp
        "is_encrypted": bool,
        "response_status": str,
        "security_tier": str,         # "standard", "high", or "maximum"
        "memory_protection": dict,    # server-side memory protection info
        "cuda_device": dict,          # privacy-safe GPU info (hashed identifiers)
        "tpm_attestation": {          # TPM 2.0 hardware attestation (see Security Guide)
            "is_available": bool,
            # Present only when is_available is True:
            "pcr_banks": str,         # e.g. "sha256:0,7,10"
            "pcr_values": dict,       # {bank: {pcr_index: hex_digest}}
            "quote_b64": str,         # base64-encoded TPMS_ATTEST (signed by AIK)
            "signature_b64": str,     # base64-encoded TPMT_SIGNATURE
            "aik_pubkey_b64": str,    # base64-encoded TPM2B_PUBLIC (ephemeral AIK)
        }
    }
}

The _metadata field is added by the client library and is not part of the OpenAI API response format. See the Security Guide for how to interpret and verify tpm_attestation.

acreate(model, messages, **kwargs)

Async alias for create() method.

Parameters: Same as create() method

Returns: Same as create() method

SecureCompletionClient Class

The SecureCompletionClient class handles the underlying encryption, key management, and API communication.

Constructor

SecureCompletionClient(
    router_url: str = "https://api.nomyo.ai",
    allow_http: bool = False,
    max_retries: int = 2
)

Parameters:

• router_url (str): Base URL of the NOMYO Router (must use HTTPS for production)
• allow_http (bool): Allow HTTP connections (ONLY for local development, never in production)
• max_retries (int): Number of retries on retryable errors (429, 500, 502, 503, 504, network errors). Uses exponential backoff. Default: 2

Methods

generate_keys(save_to_file: bool = False, key_dir: str = "client_keys", password: Optional[str] = None)

Generate RSA key pair for secure communication.

Parameters:

• save_to_file (bool): Whether to save keys to files
• key_dir (str): Directory to save keys (if save_to_file is True)
• password (Optional[str]): Optional password to encrypt private key

load_keys(private_key_path: str, public_key_path: Optional[str] = None, password: Optional[str] = None)

Load RSA keys from files.

Parameters:

• private_key_path (str): Path to private key file
• public_key_path (Optional[str]): Path to public key file (optional, derived from private key if not provided)
• password (Optional[str]): Optional password for encrypted private key

fetch_server_public_key()

Fetch the server's public key from the /pki/public_key endpoint.

Returns: Server's public key as PEM string

encrypt_payload(payload: Dict[str, Any])

Encrypt a payload using hybrid encryption (AES-256-GCM + RSA-OAEP).

Parameters:

• payload (Dict[str, Any]): Dictionary containing the chat completion request

Returns: Encrypted payload as bytes

decrypt_response(encrypted_response: bytes, payload_id: str)

Decrypt a response from the secure endpoint.

Parameters:

• encrypted_response (bytes): Encrypted response bytes
• payload_id (str): Payload ID for metadata verification

Returns: Decrypted response dictionary

send_secure_request(payload: Dict[str, Any], payload_id: str, api_key: Optional[str] = None, security_tier: Optional[str] = None)

Send a secure chat completion request to the router.

Parameters:

• payload (Dict[str, Any]): Chat completion request payload
• payload_id (str): Unique identifier for this request
• api_key (Optional[str]): Optional API key for bearer authentication
• security_tier (Optional[str]): Optional security tier for routing

Returns: Decrypted response from the LLM

Exception Classes

APIError

Base class for all API-related errors.

AuthenticationError

Raised when authentication fails (e.g., invalid API key).

InvalidRequestError

Raised when the request is invalid (HTTP 400).

APIConnectionError

Raised when there's a connection error.

RateLimitError

Raised when rate limit is exceeded (HTTP 429).

ServerError

Raised when the server returns an error (HTTP 500).

SecurityError

Raised when a security violation is detected.