Skip to content

ICNLI Specification v1.0

Infrastructure Contextual Natural Language Interface

Version: 1.0.0-draft
Status: Draft Specification
Date: January 2026
Created by: Valentin Scerbacov
Copyright: © 2026 Blue Bee Web, Inc. All rights reserved.
Trademark: ICNLI™ is a trademark of Blue Bee Web, Inc.

Abstract

ICNLI (Infrastructure Contextual Natural Language Interface) is an open specification for building context-aware natural language interfaces to infrastructure management systems. Unlike traditional chatbots or command-line interfaces, ICNLI-compliant systems maintain deep, persistent context about the user, their resources, and the relationships between infrastructure components.

This specification defines the core principles, context model, interaction patterns, safety requirements, and conformance levels for ICNLI implementations.

Table of Contents

  1. Introduction
  2. Terminology
  3. Core Principles
  4. Context Model
  5. Interaction Protocol
  6. Safety Layer
  7. Tool Interface
  8. Multi-Channel Support
  9. Conformance Levels
  10. Security Considerations
  11. Implementation Guidelines
  12. Appendices

1. Introduction

1.1 Purpose

The purpose of this specification is to define a standard interface for natural language interaction with infrastructure management systems that:

  • Maintains deep contextual awareness of user resources
  • Provides safe, reversible operations with explicit confirmation
  • Supports multiple communication channels uniformly
  • Enables AI-assisted infrastructure management while preserving human control

1.2 Scope

This specification covers:

  • Context model and hierarchy
  • Interaction patterns and conversation flow
  • Safety mechanisms and confirmation protocols
  • Tool interface contracts
  • Multi-channel message formats
  • Conformance requirements

This specification does NOT cover:

  • Specific AI/LLM implementation details
  • Infrastructure-specific operations (these are defined in domain extensions)
  • User interface design
  • Backend infrastructure architecture

1.3 Motivation

Traditional infrastructure management interfaces fall into two categories:

  1. GUI Dashboards - Click-heavy, context-switching, manual
  2. CLI/API - Powerful but requires expertise, no natural language

Modern AI assistants can understand natural language but lack:

  • Persistent context about YOUR infrastructure
  • Real ability to execute operations
  • Safety mechanisms for destructive actions
  • Deep integration with management systems

ICNLI bridges this gap by defining how natural language interfaces should integrate with infrastructure systems while maintaining context, safety, and user control.

1.4 Design Goals

Goal Description
Context-First Every interaction occurs within rich, multi-level context
Safe by Default All mutations require explicit confirmation
Channel-Agnostic Same capabilities across web, mobile, messaging, voice
Human-in-the-Loop AI assists, human decides
Auditable Every action is logged with full context
Extensible Domain-specific extensions without core changes

2. Terminology

2.1 Key Terms

Term Definition
ICNLI Infrastructure Contextual Natural Language Interface
Context The complete state of user's resources, permissions, and session
Context Level A layer in the hierarchical context model
Tool An executable function that performs an infrastructure operation
Channel A communication medium (web, telegram, discord, voice, etc.)
Mutation Any operation that changes infrastructure state
Confirmation Explicit user approval before executing a mutation
TWO-STEP The confirmation pattern: Propose → Confirm → Execute
Session A bounded conversation with maintained state
Actor The authenticated entity initiating requests (user, service, system)

2.2 Conformance Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

3. Core Principles

3.1 Principle 1: Context is Primary

Every ICNLI interaction MUST occur within a defined context. The system MUST NOT process requests without first establishing:

  1. Actor Identity - Who is making the request
  2. Actor Permissions - What they are allowed to do
  3. Resource Context - What resources are relevant to the request
[ANTI-PATTERN]
User: "Delete the database"
System: "Deleting database..." ❌

[ICNLI PATTERN]
User: "Delete the database"
System: "I see you have 3 databases:
         - myapp_prod (2.3GB, active)
         - myapp_staging (500MB, idle)
         - myapp_backup_old (1.2GB, idle)
         Which database would you like to delete?"

3.2 Principle 2: Safety by Design

All operations that modify infrastructure state (mutations) MUST follow the TWO-STEP confirmation pattern:

Step 1: Propose - System analyzes the request - System gathers all affected resources - System presents a clear summary of intended changes - System requests explicit confirmation

Step 2: Execute - User provides explicit confirmation - System executes the operation - System reports results

User: "Restart my server"

System: "I'll restart your server 'web-prod-01'.

         ⚠️ Impact:
         - Server will be unavailable for ~2-3 minutes
         - 12 active websites will go offline temporarily
         - 3 background jobs will be interrupted

         Do you want to proceed? (yes/no)"

User: "yes"

System: "✅ Server 'web-prod-01' restarted successfully.
         - Downtime: 2m 14s
         - All 12 websites are back online
         - Background jobs resumed"

3.3 Principle 3: Channel Neutrality

ICNLI implementations MUST provide equivalent functionality across all supported channels. A user SHOULD be able to perform any operation from any channel.

[Web Interface]
User clicks: [Restart Server]

[Telegram]
User types: "Restart my server"

[Voice]
User says: "Hey Webbee, restart my server"

→ All three trigger the same TWO-STEP flow
→ All three have access to same context
→ All three produce equivalent results

3.4 Principle 4: Transparency

The system MUST be transparent about:

  1. What it knows - Available context and its sources
  2. What it will do - Exact operations before execution
  3. What it did - Complete audit trail after execution
  4. What it cannot do - Clear limitations and permission boundaries

3.5 Principle 5: Graceful Degradation

When context is incomplete or uncertain, the system MUST:

  1. Clearly state what is unknown
  2. Ask clarifying questions
  3. Never assume or guess for destructive operations
User: "Update the SSL certificate"

System: "I found 5 domains with SSL certificates:
         - example.com (expires in 3 days) ⚠️
         - shop.example.com (valid for 89 days)
         - api.example.com (valid for 89 days)
         - staging.example.com (expired 2 days ago) ❌
         - old-site.example.com (valid for 234 days)

         Which certificate would you like to update?
         Or say 'all expiring' to update those expiring soon."

4. Context Model

4.1 Context Hierarchy

ICNLI defines a hierarchical context model with mandatory and optional levels:

┌─────────────────────────────────────────────────────────────┐
│ Level 0: PLATFORM CONTEXT (Global)                          │
│ Platform capabilities, available tools, system status       │
├─────────────────────────────────────────────────────────────┤
│ Level 1: ACTOR CONTEXT (Who)                                │
│ Identity, authentication, roles, permissions                │
├─────────────────────────────────────────────────────────────┤
│ Level 2: ACCOUNT CONTEXT (Ownership)                        │
│ Billing, subscription, resource quotas, limits              │
├─────────────────────────────────────────────────────────────┤
│ Level 3: SERVICE CONTEXT (What)                             │
│ Purchased services, their status, configuration             │
├─────────────────────────────────────────────────────────────┤
│ Level 4: SERVER CONTEXT (Where)                             │
│ Server resources, OS, specs, location                       │
├─────────────────────────────────────────────────────────────┤
│ Level 5: APPLICATION CONTEXT (Apps)                         │
│ Websites, databases, email, applications                    │
├─────────────────────────────────────────────────────────────┤
│ Level 6: RESOURCE CONTEXT (Details)                         │
│ Files, records, configurations, metrics                     │
├─────────────────────────────────────────────────────────────┤
│ Level 7: WEBBEE WORKER CONTEXT (When)                       │
│ History, trends, scheduled operations, predictions          │
├─────────────────────────────────────────────────────────────┤
│ Level 8: RELATIONSHIP CONTEXT (How)                         │
│ Dependencies, impacts, cross-resource relationships         │
└─────────────────────────────────────────────────────────────┘

4.2 Context Requirements

4.2.1 Mandatory Context (Levels 0-2)

Every ICNLI implementation MUST maintain:

Level Context Required Data
0 Platform Available tools, system status, version
1 Actor Identity, authentication status, roles
2 Account Ownership, basic permissions

4.2.2 Domain Context (Levels 3-6)

Domain-specific implementations SHOULD maintain:

Level Context Example Data
3 Service Hosting plans, subscriptions, quotas
4 Server IP, OS, resources, control panel
5 Application Websites, databases, email accounts
6 Resource Files, DNS records, SSL certificates

4.2.3 Advanced Context (Levels 7-8)

Sophisticated implementations MAY maintain:

Level Context Example Data
7 Worker Historical data, trends, predictions
8 Relationship Dependencies, impact analysis

4.3 Context Resolution

When processing a request, the system MUST resolve context in order:

def resolve_context(request: Request) -> Context:
    """
    Context resolution algorithm (pseudocode)
    """
    context = Context()

    # Level 0: Platform (always available)
    context.platform = get_platform_context()

    # Level 1: Actor (from authentication)
    context.actor = authenticate(request)
    if not context.actor:
        raise AuthenticationRequired()

    # Level 2: Account (from actor)
    context.account = get_account(context.actor)

    # Level 3+: Lazy loading based on request
    if request.mentions_service():
        context.service = resolve_service(request, context)

    if request.mentions_server():
        context.server = resolve_server(request, context)

    # ... continue for deeper levels

    return context

4.4 Context Example

Complete context for request "Show me my website traffic":

{
  "platform": {
    "name": "Webbee",
    "version": "8.43",
    "tools_available": 128,
    "status": "operational"
  },
  "actor": {
    "id": "user_12345",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "client",
    "authenticated_via": "telegram",
    "session_id": "sess_abc123"
  },
  "account": {
    "id": "acc_67890",
    "type": "premium",
    "services_count": 3,
    "balance": 150.00,
    "currency": "USD"
  },
  "services": [
    {
      "id": "svc_001",
      "type": "vps_hosting",
      "name": "Production Server",
      "status": "active",
      "server": {
        "id": "srv_web01",
        "ip": "192.168.1.100",
        "os": "Ubuntu 22.04",
        "control_panel": "Web Control Panel",
        "websites": [
          {
            "domain": "example.com",
            "type": "wordpress",
            "traffic_30d": 125000,
            "status": "active"
          },
          {
            "domain": "blog.example.com",
            "type": "static",
            "traffic_30d": 45000,
            "status": "active"
          }
        ]
      }
    }
  ],
  "worker": {
    "last_interaction": "2026-01-02T15:30:00Z",
    "session_started": "2026-01-03T10:00:00Z",
    "previous_requests": [
      "Check server status",
      "List my domains"
    ]
  },
  "relationships": {
    "example.com": {
      "depends_on": ["srv_web01", "dns_zone_example"],
      "impacts": ["email_example.com", "ssl_example.com"]
    }
  }
}

5. Interaction Protocol

5.1 Request Types

ICNLI defines four request types:

Type Description Confirmation Required
QUERY Read-only information retrieval No
MUTATION State-changing operation Yes (TWO-STEP)
NAVIGATION Context switching No
META System/help requests No

5.2 Request Classification

Implementations MUST classify incoming requests:

def classify_request(request: NaturalLanguageRequest) -> RequestType:
    """
    Request classification algorithm (pseudocode)
    """
    # Keywords indicating mutations
    mutation_indicators = [
        "create", "delete", "remove", "update", "change",
        "restart", "stop", "start", "enable", "disable",
        "install", "uninstall", "modify", "reset", "clear"
    ]

    # Keywords indicating queries
    query_indicators = [
        "show", "list", "get", "display", "what", "how many",
        "status", "check", "view", "tell me", "find"
    ]

    # Analyze intent
    if any(kw in request.text.lower() for kw in mutation_indicators):
        return RequestType.MUTATION
    elif any(kw in request.text.lower() for kw in query_indicators):
        return RequestType.QUERY
    elif request.is_context_switch():
        return RequestType.NAVIGATION
    else:
        return RequestType.META

5.3 TWO-STEP Confirmation Protocol

All MUTATION requests MUST follow this protocol:

┌─────────────────────────────────────────────────────────────┐
│                    TWO-STEP PROTOCOL                        │
└─────────────────────────────────────────────────────────────┘

Step 1: PROPOSAL
────────────────
User Request → Parse → Classify as MUTATION → Gather Context
                                                    ↓
                                            Generate Proposal
                                                    ↓
                                            Present to User
                                            ┌─────────────────┐
                                            │ Summary         │
                                            │ Affected Items  │
                                            │ Impact Warning  │
                                            │ [Confirm?]      │
                                            └─────────────────┘

Step 2: EXECUTION
─────────────────
User Confirms → Validate Confirmation → Execute Operation
                                              ↓
                                        Report Results
                                        ┌─────────────────┐
                                        │ ✅ Success      │
                                        │ Changed Items   │
                                        │ Duration        │
                                        │ Next Steps      │
                                        └─────────────────┘

5.4 Confirmation Tokens

To prevent accidental confirmations, implementations SHOULD use confirmation tokens:

{
  "proposal_id": "prop_xyz789",
  "action": "delete_database",
  "target": "myapp_prod",
  "expires_at": "2026-01-03T10:05:00Z",
  "confirmation_required": "yes",
  "valid_confirmations": ["yes", "confirm", "proceed", "do it"]
}

Implementations MUST: - Generate unique proposal IDs - Expire proposals after timeout (RECOMMENDED: 5 minutes) - Reject confirmations for expired proposals - Reject confirmations that don't match the proposal

5.5 Conversation Flow

┌──────────┐     ┌───────────┐     ┌──────────┐     ┌──────────┐
│  START   │────▶│  CONTEXT  │────▶│ PROCESS  │────▶│ RESPOND  │
└──────────┘     │  RESOLVE  │     │ REQUEST  │     └──────────┘
                 └───────────┘     └──────────┘           │
                       │                │                 │
                       ▼                ▼                 ▼
                 ┌───────────┐   ┌────────────┐    ┌──────────┐
                 │  Missing  │   │ MUTATION?  │    │  AWAIT   │
                 │  Context  │   │  TWO-STEP  │    │  INPUT   │
                 └───────────┘   └────────────┘    └──────────┘
                       │                │                 │
                       ▼                ▼                 │
                 ┌───────────┐   ┌────────────┐           │
                 │   ASK     │   │  CONFIRM?  │◀─────────┘
                 │ CLARIFY   │   │  EXECUTE   │
                 └───────────┘   └────────────┘

6. Safety Layer

6.1 Safety Classification

All tools MUST be classified by safety level:

Level Name Description Example
0 READ No side effects List servers, show status
1 SAFE_WRITE Reversible changes Update DNS TTL, change email
2 WRITE Significant changes Create database, add domain
3 DANGEROUS Potentially destructive Delete files, drop database
4 CRITICAL Irreversible/severe impact Delete server, purge backups

6.2 Safety Requirements by Level

Level Confirmation Audit Backup Cooling Period
0 No Optional No No
1 Optional Yes No No
2 Yes Yes Recommended No
3 Yes + Details Yes Required Recommended
4 Yes + Explicit Yes Required Required (30s)

6.3 Impact Analysis

Before proposing a mutation, implementations MUST analyze impact:

def analyze_impact(operation: Operation, context: Context) -> Impact:
    """
    Impact analysis (pseudocode)
    """
    impact = Impact()

    # Direct targets
    impact.direct_targets = operation.get_targets()

    # Cascade effects (from relationship context)
    for target in impact.direct_targets:
        dependents = context.relationships.get_dependents(target)
        impact.cascade_targets.extend(dependents)

    # Risk assessment
    impact.risk_level = assess_risk(
        operation.type,
        len(impact.direct_targets),
        len(impact.cascade_targets),
        context.worker.is_peak_hours()
    )

    # Reversibility
    impact.reversible = operation.is_reversible()
    impact.backup_available = check_backup(impact.direct_targets)

    return impact

6.4 Danger Phrase Requirements

For CRITICAL (level 4) operations, implementations MUST require explicit danger phrases:

User: "Delete my server"

System: "⚠️ CRITICAL OPERATION ⚠️

         You are about to DELETE server 'prod-web-01'.

         This will PERMANENTLY destroy:
         - 12 websites
         - 5 databases (total 15GB data)
         - 3 email accounts (2,500 emails)
         - All backups on this server

         THIS ACTION CANNOT BE UNDONE.

         To confirm, type exactly: DELETE prod-web-01"

User: "DELETE prod-web-01"

System: "✅ Server deletion initiated.
         - Server will be destroyed in 30 seconds
         - Type 'CANCEL' to abort"

6.5 Role-Based Safety

Implementations MUST enforce role-based access:

roles:
  guest:
    allowed_safety_levels: [0]
    requires_owner_approval: true

  client:
    allowed_safety_levels: [0, 1, 2, 3]
    requires_owner_approval: false
    restricted_operations:
      - server_delete
      - account_delete

  admin:
    allowed_safety_levels: [0, 1, 2, 3, 4]
    requires_owner_approval: false
    audit_level: detailed

7. Tool Interface

7.1 Tool Definition Schema

Every ICNLI tool MUST be defined using this schema:

tool:
  name: string                    # Unique identifier
  display_name: string            # Human-readable name
  description: string             # What the tool does
  category: string                # Grouping category
  safety_level: integer           # 0-4 safety classification

  parameters:
    - name: string
      type: string                # string, integer, boolean, array, object
      required: boolean
      description: string
      validation: object          # Optional validation rules

  returns:
    type: string
    description: string
    schema: object                # JSON Schema of return value

  requires_context:
    - string                      # Required context levels

  examples:
    - input: string               # Example natural language
      parameters: object          # Resolved parameters
      output: string              # Example response

7.2 Tool Example

tool:
  name: website_create
  display_name: Create Website
  description: Creates a new website/domain on the specified server
  category: websites
  safety_level: 2

  parameters:
    - name: domain
      type: string
      required: true
      description: Domain name for the website
      validation:
        pattern: "^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\\.[a-zA-Z]{2,}$"

    - name: server_id
      type: string
      required: false
      description: Target server (defaults to user's primary server)

    - name: php_version
      type: string
      required: false
      description: PHP version to use
      default: "8.2"
      validation:
        enum: ["7.4", "8.0", "8.1", "8.2", "8.3"]

    - name: ssl_enabled
      type: boolean
      required: false
      default: true
      description: Enable free SSL certificate

  returns:
    type: object
    description: Created website details
    schema:
      type: object
      properties:
        domain:
          type: string
        document_root:
          type: string
        php_version:
          type: string
        ssl_status:
          type: string
        ftp_username:
          type: string

  requires_context:
    - actor
    - account
    - server

  examples:
    - input: "Create a website for example.com"
      parameters:
        domain: "example.com"
        ssl_enabled: true
      output: "Created website example.com with SSL enabled"

    - input: "Add new site shop.mystore.com with PHP 8.3"
      parameters:
        domain: "shop.mystore.com"
        php_version: "8.3"
        ssl_enabled: true
      output: "Created website shop.mystore.com with PHP 8.3"

7.3 Tool Categories

ICNLI defines standard tool categories:

Category Description Example Tools
servers Server management restart, status, resources
websites Website operations create, delete, configure
databases Database management create, backup, restore
dns DNS record management add, update, delete records
ssl SSL certificate operations issue, renew, install
email Email account management create, configure
files File operations read, write, permissions
backups Backup management create, restore, schedule
monitoring Metrics and alerts status, traffic, errors
security Security operations firewall, malware scan
billing Billing and account invoices, payments
system System operations meta, help, settings

7.4 Tool Discovery

Implementations MUST provide tool discovery:

endpoint: /icnli/tools
method: GET
response:
  tools_count: 128
  categories:
    - name: servers
      tools_count: 15
      tools:
        - name: server_restart
          display_name: Restart Server
          safety_level: 3
        - name: server_status
          display_name: Server Status
          safety_level: 0
        # ...

8. Multi-Channel Support

8.1 Channel Requirements

ICNLI implementations MUST support at least one channel and SHOULD support multiple channels with equivalent functionality.

8.2 Standard Channels

Channel Type Input Output
Web GUI Text + Click Rich HTML
Telegram Messaging Text + Commands Markdown + Buttons
Discord Messaging Text + Commands Markdown + Buttons
Voice Audio Speech (STT) Speech (TTS)
API Programmatic JSON JSON
CLI Terminal Text Plain text

8.3 Channel Abstraction

Implementations MUST abstract channel-specific details:

class Channel(ABC):
    """Abstract channel interface"""

    @abstractmethod
    def receive_message(self) -> Message:
        """Receive user input"""
        pass

    @abstractmethod
    def send_message(self, response: Response) -> None:
        """Send response to user"""
        pass

    @abstractmethod
    def send_confirmation_request(self, proposal: Proposal) -> None:
        """Request confirmation with appropriate UI"""
        pass

    @abstractmethod
    def get_actor_context(self) -> ActorContext:
        """Get authenticated user context"""
        pass

8.4 Response Adaptation

Responses MUST be adapted to channel capabilities:

def adapt_response(response: Response, channel: Channel) -> ChannelResponse:
    """
    Adapt response to channel capabilities
    """
    if channel.supports_rich_formatting():
        return format_rich(response)
    elif channel.supports_markdown():
        return format_markdown(response)
    elif channel.is_voice():
        return format_speech(response)
    else:
        return format_plain_text(response)

8.5 Channel-Specific Considerations

8.5.1 Voice Channel

For voice channels, implementations MUST: - Use clear, concise responses suitable for audio - Spell out important values (IPs, passwords) - Provide audio confirmation before critical actions - Support interruption for long responses

[Voice Request]
User: "What's my server IP?"

[Voice Response]
"Your server IP is one nine two dot one six eight dot one dot one hundred.
 That's 192.168.1.100. Would you like me to repeat that?"

8.5.2 Messaging Channels (Telegram/Discord)

For messaging channels, implementations SHOULD: - Use inline buttons for common actions - Support command shortcuts (/status, /help) - Provide message threading for complex operations - Respect rate limits

9. Conformance Levels

9.1 Level Definitions

ICNLI defines three conformance levels:

Level Name Requirements
1 Basic Core principles, TWO-STEP, basic context
2 Standard Full context model, multi-channel, safety layer
3 Advanced Relationship context, impact analysis, voice

9.2 Level 1: Basic Conformance

Implementations at Level 1 MUST:

  • [ ] Implement TWO-STEP confirmation for all mutations
  • [ ] Maintain actor context (Level 1)
  • [ ] Maintain account context (Level 2)
  • [ ] Provide tool discovery endpoint
  • [ ] Log all operations with timestamps
  • [ ] Support at least one channel

9.3 Level 2: Standard Conformance

Implementations at Level 2 MUST:

  • [ ] All Level 1 requirements
  • [ ] Implement full context model (Levels 0-6)
  • [ ] Implement safety classification (Levels 0-4)
  • [ ] Support at least two channels
  • [ ] Provide impact summaries for mutations
  • [ ] Implement role-based access control
  • [ ] Provide confirmation tokens with expiration
  • [ ] Support context switching within sessions

9.4 Level 3: Advanced Conformance

Implementations at Level 3 MUST:

  • [ ] All Level 2 requirements
  • [ ] Implement worker context (Level 7)
  • [ ] Implement relationship context (Level 8)
  • [ ] Provide cascade impact analysis
  • [ ] Support voice channel with STT/TTS
  • [ ] Implement danger phrase confirmation for critical ops
  • [ ] Provide cooling period for irreversible operations
  • [ ] Support cross-session context persistence

9.5 Conformance Declaration

Implementations MUST declare their conformance level:

{
  "icnli": {
    "specification_version": "1.0",
    "conformance_level": 2,
    "channels": ["web", "telegram", "api"],
    "tools_count": 128,
    "context_levels": [0, 1, 2, 3, 4, 5, 6],
    "safety_levels": [0, 1, 2, 3, 4],
    "vendor": "Webbee",
    "vendor_version": "8.43"
  }
}

10. Security Considerations

10.1 Authentication

Implementations MUST: - Authenticate users before processing any request - Support industry-standard authentication methods - Never store credentials in plain text - Implement session timeout

10.2 Authorization

Implementations MUST: - Verify permissions before tool execution - Implement least-privilege principle - Log authorization failures - Support permission delegation with limits

10.3 Input Validation

Implementations MUST: - Validate all input against defined schemas - Sanitize input to prevent injection attacks - Reject malformed requests with clear errors - Implement rate limiting

10.4 Audit Logging

Implementations MUST log: - All authentication events - All tool executions with parameters - All confirmation responses - All errors and exceptions

Log format:

{
  "timestamp": "2026-01-03T10:15:30.123Z",
  "event_type": "tool_execution",
  "actor_id": "user_12345",
  "session_id": "sess_abc123",
  "channel": "telegram",
  "tool": "website_create",
  "parameters": {
    "domain": "example.com"
  },
  "result": "success",
  "duration_ms": 1523
}

10.5 Data Protection

Implementations MUST: - Encrypt sensitive data at rest - Use TLS for all communications - Mask sensitive values in logs (passwords, keys) - Implement data retention policies

11. Implementation Guidelines

11.1 Architecture Recommendations

┌─────────────────────────────────────────────────────────────┐
│                      ICNLI SYSTEM                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Web UI    │  │  Telegram   │  │   Voice     │         │
│  │   Channel   │  │   Channel   │  │   Channel   │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┼────────────────┘                 │
│                          ▼                                  │
│              ┌───────────────────────┐                      │
│              │    Channel Gateway    │                      │
│              │  (Auth, Rate Limit)   │                      │
│              └───────────┬───────────┘                      │
│                          ▼                                  │
│              ┌───────────────────────┐                      │
│              │   Context Aggregator  │                      │
│              │   (Build Full Context)│                      │
│              └───────────┬───────────┘                      │
│                          ▼                                  │
│              ┌───────────────────────┐                      │
│              │      AI Engine        │                      │
│              │  (Intent, Tool Call)  │                      │
│              └───────────┬───────────┘                      │
│                          ▼                                  │
│              ┌───────────────────────┐                      │
│              │    Safety Layer       │                      │
│              │  (Classify, Confirm)  │                      │
│              └───────────┬───────────┘                      │
│                          ▼                                  │
│              ┌───────────────────────┐                      │
│              │   Tool Orchestrator   │                      │
│              │  (Execute, Report)    │                      │
│              └───────────┬───────────┘                      │
│                          ▼                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Server    │  │   Billing   │  │   Other     │         │
│  │   Control   │  │   System    │  │   Services  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

11.2 Context Caching

For performance, implementations SHOULD: - Cache frequently accessed context - Invalidate cache on mutations - Use TTL-based expiration - Implement cache warming for common patterns

11.3 Error Handling

Implementations MUST handle errors gracefully:

class ICNLIError(Exception):
    """Base ICNLI error"""
    pass

class ContextResolutionError(ICNLIError):
    """Failed to resolve required context"""
    pass

class ToolExecutionError(ICNLIError):
    """Tool execution failed"""
    pass

class ConfirmationTimeoutError(ICNLIError):
    """Confirmation token expired"""
    pass

class PermissionDeniedError(ICNLIError):
    """Actor lacks required permission"""
    pass

Error responses:

{
  "error": {
    "type": "permission_denied",
    "message": "You don't have permission to delete servers",
    "details": {
      "required_role": "admin",
      "actor_role": "client"
    },
    "suggestion": "Contact your administrator to request elevated access"
  }
}

11.4 Testing Requirements

Implementations SHOULD include:

  1. Unit tests for each tool
  2. Integration tests for TWO-STEP flows
  3. Security tests for authorization
  4. Load tests for concurrent requests
  5. Channel tests for each supported channel

Appendices

Appendix A: Example Conversation

[Context: User "John" authenticated via Telegram]
[Services: 2 VPS hosting plans]
[Servers: prod-web-01, staging-web-01]
[Websites: 12 on prod, 3 on staging]

────────────────────────────────────────────
User: Hi, what's the status of my servers?

ICNLI: Hello John! Here's your server status:

       📊 prod-web-01 (Production)
       ├─ Status: 🟢 Online
       ├─ CPU: 45% | RAM: 62%
       ├─ Websites: 12 active
       └─ Last backup: 2h ago

       📊 staging-web-01 (Staging)
       ├─ Status: 🟢 Online
       ├─ CPU: 12% | RAM: 38%
       ├─ Websites: 3 active
       └─ Last backup: 6h ago

       Need details on any server?

────────────────────────────────────────────
User: I want to add a new website shop.mystore.com

ICNLI: I'll create the website shop.mystore.com.

       Which server should I use?
       1️⃣ prod-web-01 (recommended - 12 sites)
       2️⃣ staging-web-01 (3 sites)

────────────────────────────────────────────
User: Production

ICNLI: Perfect! Here's my plan:

       🌐 Create Website: shop.mystore.com
       ├─ Server: prod-web-01
       ├─ PHP Version: 8.2 (default)
       ├─ SSL: ✅ Free Let's Encrypt
       └─ Document Root: /home/shop_mystore_com/public_html

       Ready to create? (yes/no)

────────────────────────────────────────────
User: yes

ICNLI: ✅ Website created successfully!

       🌐 shop.mystore.com
       ├─ Status: Active
       ├─ SSL: Issued and installed
       ├─ FTP User: shop_mystore_com
       ├─ FTP Password: [Click to reveal]
       └─ Document Root: /home/shop_mystore_com/public_html

       📋 Next steps:
       • Upload your files via FTP
       • Or install WordPress: say "install WordPress"
       • Point DNS: Add A record → 192.168.1.100

────────────────────────────────────────────
User: Install WordPress

ICNLI: I'll install WordPress on shop.mystore.com.

       🔧 WordPress Installation
       ├─ Site: shop.mystore.com
       ├─ Version: 6.4.2 (latest)
       ├─ Database: shop_mystore_wp (will be created)
       └─ Admin Email: john@example.com

       Proceed with installation? (yes/no)

────────────────────────────────────────────
User: yes

ICNLI: Installing WordPress... ⏳

       ✅ WordPress installed successfully!

       🔐 Admin Access
       ├─ URL: https://shop.mystore.com/wp-admin
       ├─ Username: admin
       └─ Password: [Tap to copy: Xk9#mP2$vL8n]

       ⚠️ Security tip: Change the default password after first login.

       Your store is ready! 🎉
────────────────────────────────────────────

Appendix B: Tool Reference Template

# Template for tool definitions
tool:
  name: ""                        # snake_case, globally unique
  display_name: ""                # Human-readable
  description: ""                 # Full description
  category: ""                    # Standard category
  safety_level: 0                 # 0-4

  parameters:                     # Input parameters
    - name: ""
      type: ""                    # string|integer|boolean|array|object
      required: false
      description: ""
      default: null
      validation: {}

  returns:                        # Output definition
    type: ""
    description: ""
    schema: {}

  requires_context:               # Required context levels
    - ""

  permissions:                    # Required permissions
    - ""

  examples:                       # Usage examples
    - input: ""
      parameters: {}
      output: ""

  errors:                         # Possible errors
    - code: ""
      description: ""

Appendix C: Context Object Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ICNLI Context",
  "type": "object",
  "properties": {
    "platform": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "version": {"type": "string"},
        "tools_available": {"type": "integer"},
        "status": {"type": "string"}
      },
      "required": ["name", "version"]
    },
    "actor": {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "name": {"type": "string"},
        "email": {"type": "string"},
        "role": {"type": "string", "enum": ["guest", "client", "admin"]},
        "authenticated_via": {"type": "string"},
        "session_id": {"type": "string"}
      },
      "required": ["id", "role"]
    },
    "account": {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "type": {"type": "string"},
        "services_count": {"type": "integer"},
        "balance": {"type": "number"},
        "currency": {"type": "string"}
      },
      "required": ["id"]
    },
    "services": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "worker": {
      "type": "object",
      "properties": {
        "last_interaction": {"type": "string", "format": "date-time"},
        "session_started": {"type": "string", "format": "date-time"},
        "previous_requests": {"type": "array", "items": {"type": "string"}}
      }
    },
    "relationships": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "depends_on": {"type": "array", "items": {"type": "string"}},
          "impacts": {"type": "array", "items": {"type": "string"}}
        }
      }
    }
  },
  "required": ["platform", "actor"]
}

Appendix D: Revision History

Version Date Changes
1.0.0-draft 2026-01 Initial draft specification

About the Author

Valentin Scerbacov is the creator of ICNLI, Webbee, and WebHostMost. This specification was developed based on years of practical experience building AI-powered infrastructure management systems.

ICNLI represents a new approach to human-infrastructure interaction, combining natural language understanding with deep contextual awareness.

License

© 2026 Blue Bee Web, Inc. All rights reserved.

ICNLI™ and Webbee™ are trademarks of Blue Bee Web, Inc.

This specification is provided for reference and educational purposes only. No license to implement, copy, modify, or create derivative works is granted without explicit written permission from Blue Bee Web, Inc.

For licensing inquiries, partnership opportunities, or implementation permissions: - Email: license@icnli.org - Website: icnli.org - Company: Blue Bee Web, Inc.

Unauthorized use, reproduction, or distribution of this specification or any portion thereof may result in civil and criminal penalties.

END OF SPECIFICATION