# Examples

Complete code examples for NCN Network client integration.

***

## Python Examples

### Simple HTTP Client

```python
#!/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

```python
#!/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

```python
#!/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)

```javascript
// 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

```javascript
// 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

```typescript
// 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

```go
// 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

```rust
// 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

```bash
#!/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](/nc/neurochainai-guides/clients/grpc-client.md) - gRPC details
* [HTTP Client](/nc/neurochainai-guides/clients/http-client.md) - HTTP details
* [Payment Integration](/nc/neurochainai-guides/clients/payment-integration.md) - Add payments


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neurochain.ai/nc/neurochainai-guides/clients/examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.