Nelo AI

Nelo AI Assistant API

Your intelligent industrial automation assistant. Nelo provides AI-powered guidance for component selection, machine configuration, PLC programming, and procurement decisions with deep knowledge of your organization's equipment and documentation.

58 Features21 Built-in Tools5 Specialized ModesHybrid Query Router

Overview

Core Capabilities

• Chat Sessions: Persistent conversations with context
• Tool Integration: 21 built-in tools for data access
• Knowledge Base: Searches datasheets, manuals, docs
• Query Router: Hybrid SQL + vector search
• Organizational Learning: Adapts to your workflows
• Web Search: Real-time internet verification

Specialized Modes

• General Assistant: Balanced AI for all questions
• Component Selection: Find and compare parts
• Machine Configuration: Guided assembly and wiring
• Code Specialist: IEC 61131-3, Ladder Logic, ST
• Purchase Specialist: Supplier research, procurement

Chat Session Management

POST/v1/nelo/chat/sessionsAuth Required

Create Chat Session

Start a new conversation with Nelo. Sessions persist across messages. Enable machine_access_enabled or file_access_enabled to allow Nelo to access your data (consent tracked for GDPR compliance).

Request Body

Requestjson

{
  "session_name": "Temperature Sensor Selection",
  "mode": "component_selection",
  "machine_access_enabled": true,
  "file_access_enabled": true,
  "web_search_enabled": false
}

Response

Responsejson

{
  "id": "session_abc123",
  "session_name": "Temperature Sensor Selection",
  "mode": "component_selection",
  "user_id": "user_001",
  "machine_access_enabled": true,
  "file_access_enabled": true,
  "web_search_enabled": false,
  "message_count": 0,
  "created_at": "2024-08-26T10:00:00Z",
  "updated_at": "2024-08-26T10:00:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/nelo/chat/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/nelo/chat/sessionsAuth Required

List Chat Sessions

Retrieve all chat sessions for the current user with filtering options.

Parameters

modestring

Filter by mode (general, component_selection, etc.)

limitinteger

Max results (default: 50)

offsetinteger

Pagination offset

Response

Responsejson

[
  {
    "id": "session_abc123",
    "session_name": "Temperature Sensor Selection",
    "mode": "component_selection",
    "user_id": "user_001",
    "machine_access_enabled": true,
    "file_access_enabled": true,
    "web_search_enabled": false,
    "message_count": 12,
    "created_at": "2024-08-26T10:00:00Z",
    "updated_at": "2024-08-26T14:30:00Z"
  }
]

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/chat/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/nelo/chat/sessions/{session_id}Auth Required

Get Chat Session

Retrieve details of a specific chat session.

Parameters

session_idstringRequired

Session identifier

Response

Responsejson

{
  "id": "session_abc123",
  "session_name": "Temperature Sensor Selection",
  "mode": "component_selection",
  "user_id": "user_001",
  "machine_access_enabled": true,
  "file_access_enabled": true,
  "web_search_enabled": false,
  "message_count": 12,
  "created_at": "2024-08-26T10:00:00Z",
  "updated_at": "2024-08-26T14:30:00Z"
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/chat/sessions/{session_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/v1/nelo/chat/sessions/{session_id}/messagesAuth Required

Send Message

Send a message to Nelo and receive an AI-generated response with tool invocations.

Request Body

Requestjson

{
  "content": "I need a temperature transmitter that works in Zone 1 hazardous areas with HART protocol support",
  "attachments": []
}

Response

Responsejson

{
  "id": "msg_xyz789",
  "role": "assistant",
  "content": "Based on your requirements for a Zone 1 hazardous area temperature transmitter with HART protocol, I found several options:\n\n**Top Recommendation:**\n- **Rosemount 3144P** - Smart temperature transmitter with HART 7, ATEX/IECEx certified for Zone 1\n  - Accuracy: ±0.1%\n  - Output: 4-20mA with HART\n  - Price: $1,200-1,400\n\n[View Datasheet](pdf:file_123)\n\nWould you like me to compare this with alternatives?",
  "tools_called": [
    {
      "name": "search_global_knowledge_base",
      "input": {"query": "temperature transmitter Zone 1 HART hazardous"},
      "output": {"matches": 5, "top_score": 0.92}
    },
    {
      "name": "get_components",
      "input": {"category": "SENSOR", "manufacturer": "Rosemount"},
      "output": {"count": 3}
    }
  ],
  "confidence": 0.89,
  "sources": [
    {"file_id": "file_123", "filename": "rosemount_3144p_datasheet.pdf", "page": 2}
  ],
  "created_at": "2024-08-26T14:35:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/nelo/chat/sessions/{session_id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/nelo/chat/sessions/{session_id}/messagesAuth Required

Get Messages

Retrieve the complete message history for a chat session.

Parameters

session_idstringRequired

Session identifier

limitinteger

Max messages (default: 100)

Response

Responsejson

[
  {
    "id": "msg_001",
    "role": "user",
    "content": "I need a temperature transmitter...",
    "created_at": "2024-08-26T14:30:00Z"
  },
  {
    "id": "msg_002",
    "role": "assistant",
    "content": "Based on your requirements...",
    "tools_called": [...],
    "created_at": "2024-08-26T14:35:00Z"
  }
]

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/chat/sessions/{session_id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

DELETE/v1/nelo/chat/sessions/{session_id}Auth Required

Delete Session

Delete a chat session and all associated messages.

Parameters

session_idstringRequired

Session identifier

Response

Responsejson

{
  "success": true,
  "deleted_messages": 12
}

Try it out

cURLbash

curl -X DELETE "https://sapienstream.com/api/v1/nelo/chat/sessions/{session_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Specialized Modes

General Assistant

Balanced AI for answering any industrial automation question. Good starting point for exploratory queries.

Mode: general

Component Selection

Specialized for finding, comparing, and selecting industrial components. Deep datasheet knowledge.

Mode: component_selection

Machine Configuration

Guides through assembly, wiring, and configuration of industrial equipment. XML config generation.

Mode: machine_configuration

Code Specialist

PLC programming expert. IEC 61131-3 compliant: Ladder Logic, Structured Text, Function Blocks.

Mode: code_specialist

Purchase Specialist

Supplier research, price comparison, lead time analysis, procurement recommendations.

Mode: purchase_specialist

GET/v1/nelo/chat/modesAuth Required

List Available Modes

Get information about all available Nelo modes and their capabilities.

Response

Responsejson

[
  {
    "id": "general",
    "name": "General Assistant",
    "description": "Balanced AI for all industrial automation questions",
    "icon": "bot",
    "tools_enabled": ["get_machines", "get_components", "search_global_knowledge_base"],
    "is_default": true
  },
  {
    "id": "component_selection",
    "name": "Component Selection",
    "description": "Find and compare industrial components",
    "icon": "search",
    "tools_enabled": ["search_components", "get_component_details", "check_compatibility"],
    "is_default": false
  }
]

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/chat/modes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

21 Built-in Tools

Nelo automatically invokes these tools during conversations to gather accurate data. Tools enable real-time access to your machines, components, documents, and the global knowledge base.

Utility Tools

get_current_time

Current date/time in multiple formats and timezones

calculate

Mathematical expressions with trig and common functions

count_words

Text analysis (words, characters, lines)

get_system_info

AI capabilities and system information

Machine Access Tools

get_machines

List all machines in your organization

get_machine_by_id

Get detailed machine information

get_machine_stats

Machine analytics (overview, detailed, performance)

Component Tools

get_components

List with category/manufacturer/status filters

search_components

Search by name, model, or part number

get_component_details

Full specifications and metadata

search_component_by_name

Component + datasheet search with page citations

get_component_with_description_file

Component + GSDML/EDS/XML config content

get_component_knowledge_graph

Semantic relationships with AI reasoning

Document & Knowledge Tools

get_user_documents

User's documents + global files listing

read_document_content

Raw file content extraction

search_user_files

Search within file contents

get_global_files

Global knowledge base (datasheets, manuals)

read_global_file_content

Global file content with auto-extraction

search_global_knowledge_base

Semantic vector search across all indexed knowledge

Organization & Web Tools

get_organizational_context

Learning patterns, preferences, knowledge gaps

web_search

Internet verification via OpenAI web search

Tool Management API

GET/v1/nelo/tools/availableAuth Required

List Available Tools

Get all tools available for the current user with their schemas and descriptions.

Response

Responsejson

{
  "tools": [
    {
      "name": "search_global_knowledge_base",
      "description": "Semantic search across all indexed knowledge",
      "category": "knowledge",
      "parameters": {
        "query": {"type": "string", "required": true},
        "limit": {"type": "integer", "default": 10}
      },
      "enabled": true
    }
  ],
  "total": 21
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/tools/available" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/nelo/tools/categoriesAuth Required

Get Tool Categories

Get tools grouped by category.

Response

Responsejson

{
  "categories": [
    {"name": "utility", "tools": ["get_current_time", "calculate", "count_words"]},
    {"name": "machines", "tools": ["get_machines", "get_machine_by_id", "get_machine_stats"]},
    {"name": "components", "tools": ["get_components", "search_components", "get_component_details"]},
    {"name": "knowledge", "tools": ["search_global_knowledge_base", "read_document_content"]}
  ]
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/tools/categories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/v1/nelo/tools/executeAuth Required

Execute Tool Manually

Manually invoke a specific tool (for testing or direct API use).

Request Body

Requestjson

{
  "tool_name": "search_global_knowledge_base",
  "parameters": {
    "query": "ATEX certified temperature transmitter",
    "limit": 5
  }
}

Response

Responsejson

{
  "tool_name": "search_global_knowledge_base",
  "success": true,
  "result": {
    "matches": [
      {"file_id": "file_001", "score": 0.94, "chunk": "ATEX Zone 1 certified..."},
      {"file_id": "file_002", "score": 0.87, "chunk": "Temperature range -40°C to 85°C..."}
    ]
  },
  "execution_time_ms": 245
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/nelo/tools/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/nelo/tools/historyAuth Required

Get Tool History

View recent tool executions for debugging and analytics.

Parameters

limitinteger

Max results (default: 50)

tool_namestring

Filter by tool name

Response

Responsejson

[
  {
    "id": "exec_001",
    "tool_name": "search_global_knowledge_base",
    "session_id": "session_abc",
    "parameters": {"query": "temperature transmitter"},
    "success": true,
    "execution_time_ms": 245,
    "created_at": "2024-08-26T14:30:00Z"
  }
]

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/tools/history" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Hybrid Query Router

Nelo's Query Router intelligently determines whether to use SQL (parametric), vector search (semantic), or a hybrid approach for each query, eliminating hallucinations for technical specifications.

Routing Strategies

PARAMETRIC (SQL)

Direct database queries for precise specifications.

Example: "Show me sensors with voltage 24V and IP67 rating"

SEMANTIC (Vector)

Embedding-based search for conceptual queries.

Example: "What's the best sensor for harsh outdoor environments?"

HYBRID

Combines both for complex queries with mixed requirements.

Example: "Reliable 24V sensor for food processing"

COMMAND

Direct action requests without data retrieval.

Example: "Create a new machine called Production Line 5"

Supported Parametric Fields

These technical specifications trigger direct SQL queries for accuracy

Voltage (V)Current (A)Torque (Nm)IP RatingTemperature RangePressurePower (W/kW)Certifications (ATEX, UL, CE)Communication ProtocolDimensions

User Preferences

GET/v1/nelo/preferencesAuth Required

Get User Preferences

Retrieve current Nelo personalization settings for the authenticated user.

Response

Responsejson

{
  "default_mode": "component_selection",
  "preferred_language": "en",
  "response_verbosity": "detailed",
  "preferred_manufacturers": ["Siemens", "Rosemount", "Allen-Bradley"],
  "tool_preferences": {
    "web_search_enabled": true,
    "auto_execute_tools": true
  },
  "notification_settings": {
    "email_summaries": false
  },
  "updated_at": "2024-08-26T10:00:00Z"
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/nelo/preferences" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PUT/v1/nelo/preferencesAuth Required

Update User Preferences

Modify Nelo personalization settings.

Request Body

Requestjson

{
  "default_mode": "machine_configuration",
  "response_verbosity": "concise",
  "preferred_manufacturers": ["Siemens", "ABB"]
}

Response

Responsejson

{
  "default_mode": "machine_configuration",
  "preferred_language": "en",
  "response_verbosity": "concise",
  "preferred_manufacturers": ["Siemens", "ABB"],
  "updated_at": "2024-08-26T14:00:00Z"
}

Try it out

cURLbash

curl -X PUT "https://sapienstream.com/api/v1/nelo/preferences" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/v1/nelo/preferences/resetAuth Required

Reset Preferences

Reset all preferences to default values.

Response

Responsejson

{
  "default_mode": "general",
  "preferred_language": "en",
  "response_verbosity": "balanced",
  "preferred_manufacturers": [],
  "updated_at": "2024-08-26T14:30:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/nelo/preferences/reset" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Component Compatibility Checking

POST/v1/nelo/compatibility/checkAuth Required

Check Component Compatibility

AI-powered analysis of whether two components are compatible. Nelo reads both datasheets and provides detailed reasoning with confidence scoring.

Request Body

Requestjson

{
  "source_component_id": "comp_001",
  "target_component_id": "comp_002"
}

Response

Responsejson

{
  "compatibility_score": 0.87,
  "is_compatible": true,
  "summary": "The Rosemount 3144P temperature transmitter is compatible with the Siemens S7-1500 PLC via 4-20mA analog input.",
  "detailed_analysis": "**Electrical Compatibility:**\n- Output: 4-20mA matches S7-1500 AI module range\n- Loop power: 24V DC within transmitter's 12-45V range\n\n**Communication:**\n- HART passthrough possible with suitable AI module\n\n**Physical:**\n- Standard 2-wire connection supported",
  "concerns": [
    "HART communication requires AI-H module, not standard AI"
  ],
  "datasheets": [
    {"component_id": "comp_001", "file_id": "file_123", "filename": "rosemount_3144p.pdf"},
    {"component_id": "comp_002", "file_id": "file_456", "filename": "s7-1500_manual.pdf"}
  ],
  "created_at": "2024-08-26T14:30:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/nelo/compatibility/check" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Organizational Learning

Nelo learns from your organization's interactions to provide increasingly relevant assistance. The system tracks workflow patterns, manufacturer preferences, domain knowledge, and knowledge gaps.

Learning Context Types

Workflow Patterns

Common user intents and task sequences (e.g., "Users often search for sensors then check compatibility")

Manufacturer Preferences

Frequently used brands and suppliers (e.g., "Organization prefers Siemens PLCs")

Domain Knowledge

Technical focus areas and expertise (e.g., "Strong focus on hazardous area equipment")

Knowledge Gaps

Questions Nelo couldn't fully answer (flagged for knowledge base expansion)

// Example: Organizational Context Response
{
  "organization_id": "org_001",
  "workflow_patterns": [
    {
      "pattern": "sensor_selection_flow",
      "description": "Users typically search sensors, check compatibility, then request quote",
      "frequency": 45,
      "confidence": 0.89
    }
  ],
  "manufacturer_preferences": [
    {"manufacturer": "Siemens", "frequency": 78, "categories": ["PLC", "Drive"]},
    {"manufacturer": "Rosemount", "frequency": 34, "categories": ["Sensor"]}
  ],
  "domain_knowledge": [
    {"topic": "hazardous_areas", "expertise_level": "high", "evidence_count": 56}
  ],
  "knowledge_gaps": [
    {"topic": "cybersecurity_compliance", "query_count": 12, "resolved": false}
  ],
  "updated_at": "2024-08-26T14:30:00Z"
}

Data Access Consent (GDPR)

Nelo respects data privacy. Consent for machine and file data access is managed through chat session settings, not separate endpoints.

• machine_access_enabled: Set in session create/update to allow machine data access
• file_access_enabled: Set in session create/update to allow file data access
• Consent is automatically tracked for GDPR compliance
• Toggle off at any time to revoke access

Content Deduplication

Nelo uses SHA256 content hashing to detect duplicate documents before processing. This saves API costs and ensures consistent responses across identical content.

How It Works

• SHA256 hash computed on file upload
• Hash checked against existing files
• Duplicate files linked to original vectors
• No redundant OpenAI embedding calls

Benefits

• Reduced API costs (no duplicate embeddings)
• Faster processing for known content
• Consistent search results
• Efficient storage utilization