Compute API

The Cognitora Compute API enables you to autonomously provision, execute, and manage containerized workloads.

Basic Execution

You can execute a workload by providing a Docker image and a command. The API supports public images from Docker Hub or any other public container registry.

cURL Example

Here is a basic example of how to execute a container using a cURL command.

# Get your API URL from deployment output
API_URL="https://your-service-url.run.app"

# Create secure microVM execution
curl -X POST $API_URL/api/v1/executions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "docker.io/library/python:3.11-alpine",
    "command": ["python", "-c", "print(\\"Hello from secure microVM!\\")"],
    "cpuCores": 1,
    "memoryMb": 512,
    "timeoutSeconds": 60
  }'

Python SDK Example

from cognitora import Cognitora

client = Cognitora(api_key="your_api_key")

execution = client.compute.create_execution(
    image="docker.io/library/python:3.11-slim",
    command=["python", "-c", "print('Hello from a container!')"],
    cpu_cores=1.0,
    memory_mb=512,
)

print(f"Execution ID: {execution.id}")
print(f"Status: {execution.status}")

JavaScript/TypeScript SDK Example

import { Cognitora } from '@cognitora/sdk';

const client = new Cognitora({ apiKey: 'your_api_key' });

const execution = await client.compute.createExecution({
  image: 'docker.io/library/node:18-alpine',
  command: ['node', '-e', "console.log('Hello from a container!')"],
  cpuCores: 1.0,
  memoryMb: 512,
});

console.log(`Execution ID: ${execution.id}`);
console.log(`Status: ${execution.status}`);

Resource Specification

You can specify the resources your container needs, including CPU cores and memory.

# Example of specifying more resources
execution = client.compute.create_execution(
    image="docker.io/library/python:3.11-slim",
    command=["python", "-c", "print('Hello from a container!')"],
    cpu_cores=2.0,  # Request 2 CPU cores
    memory_mb=1024, # Request 1GB of memory
)

Execution Management

You can monitor the status of your executions and retrieve their logs.

Get Execution Status

# cURL example
curl -X GET $API_URL/api/v1/executions/{execution-id} \
  -H "Authorization: Bearer <api-key>"

# Python SDK example
execution = client.compute.get_execution("execution_id")
print(f"Status: {execution.status}")

Get Execution Logs

# cURL example
curl -X GET $API_URL/api/v1/executions/{execution-id}/logs \
  -H "Authorization: Bearer <api-key>"

# Python SDK example
logs = client.compute.get_logs("execution_id")
print(logs)

Advanced Resource Specifications

GPU Workloads

# Machine learning with GPU acceleration
execution = await cg.execute({
    "image": "tensorflow/tensorflow:latest-gpu",
    "command": ["python", "train_model.py"],
    "cpu_cores": 4,
    "memory_gb": 16,
    "gpu": {
        "type": "A100",
        "count": 1,
        "memory_gb": 40
    },
    "timeout_seconds": 3600  # 1 hour for training
})

Custom Docker Images

# Use your own Docker image
execution = await cg.execute({
    "image": "myregistry/my-agent:v1.0",
    "command": ["./run_agent.sh"],
    "cpu_cores": 8,
    "memory_gb": 32,
    "volumes": {
        "/data": {
            "size_gb": 100,
            "type": "ssd"
        }
    }
})

Multi-Container Workloads

# Run multiple containers with networking
execution = await cg.execute({
    "containers": [
        {
            "name": "agent",
            "image": "my-agent:latest",
            "cpu_cores": 2,
            "memory_gb": 4
        },
        {
            "name": "database",
            "image": "postgres:15",
            "cpu_cores": 1,
            "memory_gb": 2,
            "environment": {
                "POSTGRES_PASSWORD": "secret"
            }
        }
    ],
    "network": "shared"
})

Resource Optimization

Automatic Resource Selection

Cognitora can automatically select optimal resources based on your workload:

# Let Cognitora optimize resource allocation
execution = await cg.execute({
    "image": "python:3.11",
    "command": ["python", "complex_calculation.py"],
    "optimize": "cost",  # or "speed" or "balanced"
    "max_credits": 1000  # Budget constraint
})

Preemptible Instances

Save costs with preemptible instances for fault-tolerant workloads:

execution = await cg.execute({
    "image": "my-batch-job:latest",
    "command": ["python", "batch_process.py"],
    "cpu_cores": 16,
    "memory_gb": 64,
    "preemptible": True,  # Up to 70% cost savings
    "max_preemptions": 3  # Retry limit
})

Error Handling & Resilience

Retry Logic

import asyncio
from cognitora.exceptions import ExecutionFailedError, InsufficientCreditsError

async def resilient_execution(config, max_retries=3):
    for attempt in range(max_retries):
        try:
            execution = await cg.execute(config)
            if execution.status == "completed":
                return execution
        except ExecutionFailedError as e:
            if e.code == "OUT_OF_MEMORY":
                # Increase memory and retry
                config["memory_gb"] *= 1.5
            elif attempt == max_retries - 1:
                raise
        except InsufficientCreditsError:
            print("Insufficient credits - execution paused")
            await asyncio.sleep(3600)  # Wait for credit refresh
            
        await asyncio.sleep(2 ** attempt)  # Exponential backoff

Health Checks

# Add health checks for long-running processes
execution = await cg.execute({
    "image": "my-long-running-agent:latest",
    "command": ["python", "agent.py"],
    "health_check": {
        "command": ["curl", "-f", "http://localhost:8080/health"],
        "interval_seconds": 30,
        "timeout_seconds": 5,
        "retries": 3
    }
})

Batch Processing

Parallel Execution

import asyncio

async def process_batch(items):
    # Create multiple executions in parallel
    tasks = []
    for item in items:
        task = cg.execute({
            "image": "my-processor:latest",
            "command": ["python", "process.py", item],
            "cpu_cores": 1,
            "memory_gb": 2
        })
        tasks.append(task)
    
    # Wait for all to complete
    results = await asyncio.gather(*tasks)
    return results

# Process 100 items in parallel
items = [f"item_{i}" for i in range(100)]
results = await process_batch(items)

Queue-Based Processing

# Process items from a queue
async def queue_processor():
    while True:
        # Get next item from your queue
        item = await get_next_queue_item()
        if not item:
            await asyncio.sleep(1)
            continue
            
        # Process with Cognitora
        execution = await cg.execute({
            "image": "my-processor:latest",
            "command": ["python", "process.py", item.data],
            "cpu_cores": 2,
            "memory_gb": 4
        })
        
        # Mark item as processed
        await mark_item_processed(item.id, execution.result)

Integration Examples

LangChain Integration

from langchain.agents import AgentExecutor
from cognitora.langchain import CognitoraTool

# Create a Cognitora tool for LangChain agents
cognitora_tool = CognitoraTool(
    api_key="your_api_key",
    name="execute_code",
    description="Execute Python code in a secure environment"
)

# Add to your agent
agent = AgentExecutor.from_agent_and_tools(
    agent=your_agent,
    tools=[cognitora_tool, ...other_tools],
    verbose=True
)

AutoGPT Integration

# Replace AutoGPT's local execution with Cognitora
class CognitoraExecutor:
    def __init__(self, api_key):
        self.cg = Cognitora(api_key=api_key)
    
    async def execute_python(self, code):
        execution = await self.cg.execute({
            "image": "python:3.11",
            "command": ["python", "-c", code],
            "cpu_cores": 2,
            "memory_gb": 4,
            "timeout_seconds": 300
        })
        return execution.stdout

REST API Reference

Create Execution

POST /v1/compute/executions
Content-Type: application/json
Authorization: Bearer your_api_key

{
  "image": "python:3.11",
  "command": ["python", "-c", "print('Hello World')"],
  "cpu_cores": 1,
  "memory_gb": 1,
  "timeout_seconds": 300
}

Get Execution Status

GET /v1/compute/executions/{execution_id}
Authorization: Bearer your_api_key

Stream Execution Logs

GET /v1/compute/executions/{execution_id}/logs?follow=true
Authorization: Bearer your_api_key