Examples

Complete code examples for NCN Network client integration.

---

Python Examples

Simple HTTP Client

#!/usr/bin/env python3
"""Simple NCN client using HTTP API."""
import requests
import json
import time

GATEWAY_URL = "http://localhost:8080"

def inference(model_uuid, input_data, timeout=60):
    """Submit inference and wait for result."""
    # Submit request
    response = requests.post(
        f"{GATEWAY_URL}/api/v1/inference",
        json={
            "model_uuid": model_uuid,
            "input_data": json.dumps(input_data)
        }
    )
    response.raise_for_status()
    result = response.json()
    request_id = result['request_id']
    print(f"Submitted: {request_id}")
    
    # Poll for result
    start_time = time.time()
    while time.time() - start_time < timeout:
        status_response = requests.get(
            f"{GATEWAY_URL}/api/v1/inference/{request_id}"
        )
        status = status_response.json()
        
        if status['status'] == 'completed':
            return json.loads(status['output_data'])
        elif status['status'] == 'failed':
            raise Exception(status.get('error_message', 'Unknown error'))
        
        print(f"Status: {status['status']}")
        time.sleep(1)
    
    raise TimeoutError("Request timed out")

if __name__ == "__main__":
    result = inference(
        model_uuid="bark_semantic",
        input_data={"text": "Hello, world!"}
    )
    print(f"Result: {result}")

Async HTTP Client

#!/usr/bin/env python3
"""Async NCN client using aiohttp."""
import asyncio
import aiohttp
import json

GATEWAY_URL = "http://localhost:8080"

async def inference(model_uuid, input_data, timeout=60):
    """Submit inference and wait for result (async)."""
    async with aiohttp.ClientSession() as session:
        # Submit request
        async with session.post(
            f"{GATEWAY_URL}/api/v1/inference",
            json={
                "model_uuid": model_uuid,
                "input_data": json.dumps(input_data)
            }
        ) as response:
            result = await response.json()
            request_id = result['request_id']
        
        # Poll for result
        for _ in range(timeout):
            async with session.get(
                f"{GATEWAY_URL}/api/v1/inference/{request_id}"
            ) as response:
                status = await response.json()
            
            if status['status'] == 'completed':
                return json.loads(status['output_data'])
            elif status['status'] == 'failed':
                raise Exception(status.get('error_message'))
            
            await asyncio.sleep(1)
        
        raise TimeoutError()

async def main():
    # Run multiple inferences concurrently
    tasks = [
        inference("bark_semantic", {"text": f"Hello {i}!"})
        for i in range(5)
    ]
    results = await asyncio.gather(*tasks)
    for i, result in enumerate(results):
        print(f"Result {i}: {result}")

if __name__ == "__main__":
    asyncio.run(main())

gRPC Client

#!/usr/bin/env python3
"""NCN client using gRPC."""
import grpc
import uuid
import json

# Generate these from proto file
from common_types_pb2 import InferenceRequest, TaskID
from common_types_pb2_grpc import GatewayClientServiceStub

def main():
    # Connect to gateway
    channel = grpc.insecure_channel('localhost:50051')
    stub = GatewayClientServiceStub(channel)
    
    # Create request
    request = InferenceRequest(
        request_id=str(uuid.uuid4()),
        model_uuid="bark_semantic",
        input_data=json.dumps({"text": "Hello, world!"}),
        originator_client_id="python-grpc-client"
    )
    
    # Submit
    status = stub.SubmitInferenceTask(request)
    print(f"Submitted: {status.request_id}")
    
    # Subscribe to results
    for response in stub.SubscribeToTaskUpdates(
        TaskID(id=status.request_id)
    ):
        print(f"Status: {response.status}")
        
        if response.status == "completed":
            result = json.loads(response.output_data)
            print(f"Result: {result}")
            break
        elif response.status == "failed":
            print(f"Error: {response.error_message}")
            break

if __name__ == "__main__":
    main()

---

JavaScript Examples

Browser Client (fetch)

// browser-client.js
class NCNClient {
  constructor(baseUrl = 'http://localhost:8080') {
    this.baseUrl = baseUrl;
  }

  async inference(modelUuid, inputData, timeout = 60000) {
    // Submit request
    const submitResponse = await fetch(`${this.baseUrl}/api/v1/inference`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model_uuid: modelUuid,
        input_data: JSON.stringify(inputData)
      })
    });
    
    const { request_id } = await submitResponse.json();
    console.log(`Submitted: ${request_id}`);
    
    // Poll for result
    const startTime = Date.now();
    while (Date.now() - startTime < timeout) {
      const statusResponse = await fetch(
        `${this.baseUrl}/api/v1/inference/${request_id}`
      );
      const status = await statusResponse.json();
      
      if (status.status === 'completed') {
        return JSON.parse(status.output_data);
      } else if (status.status === 'failed') {
        throw new Error(status.error_message);
      }
      
      await new Promise(r => setTimeout(r, 1000));
    }
    
    throw new Error('Timeout');
  }
}

// Usage
const client = new NCNClient();
client.inference('bark_semantic', { text: 'Hello, world!' })
  .then(result => console.log('Result:', result))
  .catch(error => console.error('Error:', error));

Node.js Client

// node-client.js
const fetch = require('node-fetch');

class NCNClient {
  constructor(baseUrl = 'http://localhost:8080') {
    this.baseUrl = baseUrl;
  }

  async inference(modelUuid, inputData, timeout = 60000) {
    // Submit
    const submitRes = await fetch(`${this.baseUrl}/api/v1/inference`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model_uuid: modelUuid,
        input_data: JSON.stringify(inputData)
      })
    });
    const { request_id } = await submitRes.json();

    // Poll
    const deadline = Date.now() + timeout;
    while (Date.now() < deadline) {
      const statusRes = await fetch(`${this.baseUrl}/api/v1/inference/${request_id}`);
      const status = await statusRes.json();

      if (status.status === 'completed') {
        return JSON.parse(status.output_data);
      }
      if (status.status === 'failed') {
        throw new Error(status.error_message);
      }

      await new Promise(r => setTimeout(r, 1000));
    }
    throw new Error('Timeout');
  }
}

// Usage
(async () => {
  const client = new NCNClient();
  const result = await client.inference('bark_semantic', { text: 'Hello!' });
  console.log('Result:', result);
})();

TypeScript Client

// ncn-client.ts
interface InferenceResult {
  tokens?: number[];
  [key: string]: any;
}

interface InferenceStatus {
  request_id: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  output_data?: string;
  error_message?: string;
}

class NCNClient {
  private baseUrl: string;

  constructor(baseUrl: string = 'http://localhost:8080') {
    this.baseUrl = baseUrl;
  }

  async inference<T = InferenceResult>(
    modelUuid: string,
    inputData: Record<string, any>,
    timeout: number = 60000
  ): Promise<T> {
    // Submit
    const submitResponse = await fetch(`${this.baseUrl}/api/v1/inference`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model_uuid: modelUuid,
        input_data: JSON.stringify(inputData)
      })
    });

    const { request_id } = await submitResponse.json();

    // Poll
    const deadline = Date.now() + timeout;
    while (Date.now() < deadline) {
      const statusResponse = await fetch(
        `${this.baseUrl}/api/v1/inference/${request_id}`
      );
      const status: InferenceStatus = await statusResponse.json();

      if (status.status === 'completed' && status.output_data) {
        return JSON.parse(status.output_data) as T;
      }
      if (status.status === 'failed') {
        throw new Error(status.error_message || 'Unknown error');
      }

      await new Promise(r => setTimeout(r, 1000));
    }

    throw new Error('Timeout');
  }
}

// Usage
const client = new NCNClient();
const result = await client.inference('bark_semantic', { text: 'Hello!' });

---

Go Example

// main.go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

type NCNClient struct {
    BaseURL string
    Client  *http.Client
}

func NewNCNClient(baseURL string) *NCNClient {
    return &NCNClient{
        BaseURL: baseURL,
        Client:  &http.Client{Timeout: 30 * time.Second},
    }
}

func (c *NCNClient) Inference(modelUUID string, inputData map[string]interface{}) (map[string]interface{}, error) {
    // Marshal input
    inputJSON, _ := json.Marshal(inputData)
    body, _ := json.Marshal(map[string]string{
        "model_uuid": modelUUID,
        "input_data": string(inputJSON),
    })

    // Submit
    resp, err := c.Client.Post(
        c.BaseURL+"/api/v1/inference",
        "application/json",
        bytes.NewBuffer(body),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var submitResult map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&submitResult)
    requestID := submitResult["request_id"].(string)

    // Poll
    for i := 0; i < 60; i++ {
        resp, _ := c.Client.Get(c.BaseURL + "/api/v1/inference/" + requestID)
        var status map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&status)
        resp.Body.Close()

        if status["status"] == "completed" {
            var result map[string]interface{}
            json.Unmarshal([]byte(status["output_data"].(string)), &result)
            return result, nil
        }
        if status["status"] == "failed" {
            return nil, fmt.Errorf("%s", status["error_message"])
        }

        time.Sleep(time.Second)
    }

    return nil, fmt.Errorf("timeout")
}

func main() {
    client := NewNCNClient("http://localhost:8080")
    result, err := client.Inference("bark_semantic", map[string]interface{}{
        "text": "Hello, world!",
    })
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    fmt.Printf("Result: %v\n", result)
}

---

Rust Example

// main.rs
use reqwest::Client;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::time::Duration;
use tokio::time::sleep;

#[derive(Serialize)]
struct InferenceRequest {
    model_uuid: String,
    input_data: String,
}

#[derive(Deserialize)]
struct SubmitResponse {
    request_id: String,
}

#[derive(Deserialize)]
struct StatusResponse {
    status: String,
    output_data: Option<String>,
    error_message: Option<String>,
}

struct NCNClient {
    base_url: String,
    client: Client,
}

impl NCNClient {
    fn new(base_url: &str) -> Self {
        Self {
            base_url: base_url.to_string(),
            client: Client::new(),
        }
    }

    async fn inference(&self, model_uuid: &str, input_data: Value) -> Result<Value, Box<dyn std::error::Error>> {
        // Submit
        let response = self.client
            .post(&format!("{}/api/v1/inference", self.base_url))
            .json(&InferenceRequest {
                model_uuid: model_uuid.to_string(),
                input_data: serde_json::to_string(&input_data)?,
            })
            .send()
            .await?;

        let submit: SubmitResponse = response.json().await?;
        println!("Submitted: {}", submit.request_id);

        // Poll
        for _ in 0..60 {
            let status: StatusResponse = self.client
                .get(&format!("{}/api/v1/inference/{}", self.base_url, submit.request_id))
                .send()
                .await?
                .json()
                .await?;

            match status.status.as_str() {
                "completed" => {
                    let output: Value = serde_json::from_str(&status.output_data.unwrap())?;
                    return Ok(output);
                }
                "failed" => {
                    return Err(status.error_message.unwrap_or_default().into());
                }
                _ => {}
            }

            sleep(Duration::from_secs(1)).await;
        }

        Err("Timeout".into())
    }
}

#[tokio::main]
async fn main() {
    let client = NCNClient::new("http://localhost:8080");
    
    match client.inference("bark_semantic", json!({"text": "Hello!"})).await {
        Ok(result) => println!("Result: {}", result),
        Err(e) => eprintln!("Error: {}", e),
    }
}

---

Bash/Shell Example

#!/bin/bash
# ncn-client.sh

GATEWAY_URL="${GATEWAY_URL:-http://localhost:8080}"
MODEL_UUID="${1:-bark_semantic}"
INPUT_TEXT="${2:-Hello, world!}"

# Submit request
echo "Submitting request..."
RESPONSE=$(curl -s -X POST "$GATEWAY_URL/api/v1/inference" \
  -H "Content-Type: application/json" \
  -d "{\"model_uuid\": \"$MODEL_UUID\", \"input_data\": \"{\\\"text\\\": \\\"$INPUT_TEXT\\\"}\"}")

REQUEST_ID=$(echo "$RESPONSE" | jq -r '.request_id')
echo "Request ID: $REQUEST_ID"

# Poll for result
echo "Waiting for result..."
for i in $(seq 1 60); do
  STATUS=$(curl -s "$GATEWAY_URL/api/v1/inference/$REQUEST_ID")
  STATE=$(echo "$STATUS" | jq -r '.status')
  
  case "$STATE" in
    completed)
      echo "Result: $(echo "$STATUS" | jq -r '.output_data')"
      exit 0
      ;;
    failed)
      echo "Error: $(echo "$STATUS" | jq -r '.error_message')"
      exit 1
      ;;
    *)
      echo "Status: $STATE"
      sleep 1
      ;;
  esac
done

echo "Timeout"
exit 1

---

Next Steps

• gRPC Client - gRPC details

• HTTP Client - HTTP details

• Payment Integration - Add payments