ICNLI Specification v1.1.3¶
Infrastructure Contextual Natural Language Interface¶
Version: 1.1.3
Status: Published Specification
Date: March 2026
Created by: Valentin Scerbacov
Copyright: © 2026 Valentin Scerbacov / Imperal, Inc.
License: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
Trademark: ICNLI™ is a registered trademark of Imperal, Inc.
Abstract¶
ICNLI (Infrastructure Contextual Natural Language Interface) is an open protocol specification that defines the operating layer between artificial intelligence and real-world operational systems.
Where TCP/IP defines how machines exchange data, and HTTP defines how systems exchange documents, ICNLI defines how AI systems acquire domain awareness, process intent, execute actions safely, and maintain continuous contextual knowledge of the environment they operate in.
ICNLI-compliant systems are not chatbots. They are operationally aware agents — systems that know their domain completely, act within it safely, and keep a human in control of every consequential decision.
The protocol is domain-agnostic by design. The context model, safety architecture, interaction patterns, and conformance requirements defined in this specification apply equally to infrastructure management, investigative case systems, clinical operations, financial systems, government services, and any other domain where complex state, multiple actors, and consequential actions intersect.
This specification defines the core principles, context model, interaction protocol, safety layer, tool interface contracts, multi-channel requirements, and conformance levels for all ICNLI implementations.
Table of Contents¶
- Introduction
- Terminology
- Core Principles
- Context Model
- Interaction Protocol
- Safety Layer
- Tool Interface
- Multi-Channel Support
- Conformance Levels
- Security Considerations
- Implementation Guidelines
- Appendices
1. Introduction¶
1.1 Purpose¶
The purpose of this specification is to define a universal protocol for AI systems that operate within real-world domains — enabling genuine situational awareness, safe execution, and persistent contextual intelligence across any operational environment.
Specifically, this specification defines how a compliant system must:
- Maintain structured, multi-level contextual awareness of its domain at all times
- Process natural language requests with domain-specific intent resolution
- Execute operations safely with mandatory human confirmation for consequential actions
- Support multiple communication channels with identical capabilities
- Preserve complete audit trails of all interactions and actions
- Remain extensible to any domain without modification to the core protocol
1.2 Scope¶
This specification covers:
- Context model and 9-level hierarchy (mandatory for all implementations)
- Interaction patterns and conversation flow
- Safety mechanisms and mandatory confirmation protocols
- Tool interface contracts and domain extension model
- Multi-channel message formats and equivalence requirements
- Conformance levels and certification requirements
This specification does NOT cover:
- Specific AI or language model implementation details — any compliant AI engine may be used
- Domain-specific operations — these are defined in domain extensions built on top of this protocol
- User interface design — channel implementations handle presentation
- Backend system architecture — implementations choose their own infrastructure
- Proprietary routing, intelligence, or execution mechanisms — these remain implementation-specific
1.3 Motivation¶
The Unfinished Revolution¶
Artificial intelligence has achieved remarkable capability in understanding human language. Yet this intelligence remains fundamentally disconnected from the operational domains it is meant to serve.
The problem is not intelligence. The problem is the absence of a structured protocol that defines how intelligence should acquire domain awareness, how it should resolve intent within that domain, how it should propose and execute actions safely, and how it should maintain continuous situational knowledge.
Without such a protocol, every AI system that attempts to operate in a real domain must solve these problems independently — inconsistently, incompletely, and without the safety guarantees that consequential operations require.
What Exists Today¶
| Interface Type | Capability | Limitation |
|---|---|---|
| GUI Dashboards | Visual, discoverable | Context-switching, click-heavy, no language |
| CLI / API | Powerful, automatable | Requires expertise, provides no awareness |
| Generic AI Assistants | Natural language | No persistent domain knowledge, no safe execution contract |
| Custom AI integrations | Domain-specific | No standard, no interoperability, reimplemented per system |
None of these provide the combination that operational domains require: persistent domain awareness + natural language + safe execution + human control.
What ICNLI Provides¶
ICNLI defines the missing layer — the protocol contract that any AI system can implement to gain genuine operational capability within any domain.
It does not define which AI engine to use. It does not define how the domain data is stored. It defines the architectural contract between the AI engine and the domain it operates in — the same way HTTP defines the contract between a browser and a server, without caring what either is built from.
1.4 Design Goals¶
| Goal | Description |
|---|---|
| Domain-Agnostic | The protocol applies to any domain — no domain assumptions in the core spec |
| Context-First | Every interaction occurs within structured, multi-level domain context — never blind |
| Safe by Default | All state-changing operations require explicit human confirmation — mandatory, not optional |
| Human-in-the-Loop | AI proposes, human decides — always, for every consequential action |
| Channel-Agnostic | Identical capabilities and context across every communication interface |
| Auditable | Every interaction and action is logged with full context and actor identity |
| Proactive | Compliant systems at higher conformance levels maintain awareness and surface issues without being asked |
| Extensible | Domain-specific capabilities are defined as extensions — the core protocol never changes |
| Implementation-Neutral | Any AI engine, any storage system, any infrastructure may be used beneath the protocol |
2. Terminology¶
2.1 Key Terms¶
| Term | Definition |
|---|---|
| ICNLI | Infrastructure Contextual Natural Language Interface — the open protocol defining the operating layer between AI and real-world operational systems |
| Domain | The operational environment an ICNLI implementation manages — any field, industry, or system |
| Context | The complete structured awareness of the domain state relevant to an actor and their request |
| Context Level | A mandatory layer in the 9-level hierarchical context model (L0–L8) |
| Tool | A defined, executable function that performs a domain operation with typed parameters, safety classification, and required permissions |
| Domain Extension | A set of domain-specific tools and context definitions built on top of the core ICNLI protocol |
| Channel | A communication interface through which actors interact with the system (web, messaging, voice, API, etc.) |
| Mutation | Any operation that changes domain state |
| Confirmation | Explicit human approval required before executing a mutation — mandatory per TWO-STEP protocol |
| TWO-STEP | The mandatory confirmation pattern: Propose (with full impact analysis) → Confirm → Execute |
| Session | A stateful interaction context maintained across one or more requests |
| Actor | The authenticated entity initiating requests — a human user, a service, or an authorized system |
| Intent Domain Router | A classification layer that resolves which operational domains are relevant to an incoming request before AI processing |
| User Intelligence Profile | A continuously maintained awareness model of the actor and their domain context — enables proactive intelligence |
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:
- Actor Identity - Who is making the request
- Actor Permissions - What they are allowed to do
- 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:
- What it knows - Available context and its sources
- What it will do - Exact operations before execution
- What it did - Complete audit trail after execution
- What it cannot do - Clear limitations and permission boundaries
3.5 Principle 5: Graceful Degradation¶
When context is incomplete or uncertain, the system MUST:
- Clearly state what is unknown
- Ask clarifying questions
- 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: RELATIONSHIP CONTEXT (Between) │
│ Connections and dependencies between entities │
├─────────────────────────────────────────────────────────────┤
│ Level 8: INTERCONNECTION CONTEXT (Across) │
│ Cross-system dependencies and cascade impact analysis │
└─────────────────────────────────────────────────────────────┘
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 | Relationships | Dependencies between entities, connection graph |
| 8 | Interconnections | Cross-system dependencies, cascade 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": "11.1",
"tools_available": 131,
"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 │
└───────────┘ └────────────┘
5b. Intent Domain Router¶
5b.1 Purpose¶
ICNLI implementations at Conformance Level 2 and above MUST implement an Intent Domain Router — a classification layer that executes before the primary AI engine processes any request.
The Intent Domain Router resolves which operational domains are relevant to an incoming request. This enables the AI engine to operate with focused context rather than the full tool registry, improving precision, response time, and accuracy.
5b.2 Domain Classification Requirements¶
Implementations MUST:
- Classify each incoming request into one or more relevant operational domains
- Pass only relevant domain tools to the AI engine
- Complete domain classification within a defined latency budget
- Fall back to full tool set if classification is uncertain
[REQUIRED BEHAVIOR]
Request: "Why is my database slow?"
Domain Router classifies: [databases, servers, applications]
AI Engine receives: only tools from these 3 domains
Result: precise, focused response
[ANTI-PATTERN]
Domain Router skipped
AI Engine receives: all 131+ tools
Result: slower, potentially less precise
5b.3 Classification Transparency¶
Implementations SHOULD expose the domain classification result in debug/audit mode so operators can verify routing correctness. The routing algorithm itself is implementation-specific and MAY be proprietary.
5b.4 Domain Registry¶
Implementations MUST maintain a Domain Registry that maps tools to domains:
domain_registry:
servers:
- server_status
- server_restart
- server_resources
# ...
databases:
- database_list
- database_create
- database_optimize
# ...
# ... additional domains
The number and naming of domains is implementation-specific. Webbee's reference implementation organizes 131 tools across 22 domains.
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: 131
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.1.3",
"conformance_level": 2,
"channels": ["web", "telegram", "api"],
"tools_count": 131,
"context_levels": [0, 1, 2, 3, 4, 5, 6, 7, 8],
"safety_levels": [0, 1, 2, 3, 4],
"vendor": "Webbee",
"vendor_version": "11.1"
}
}
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:
- Unit tests for each tool
- Integration tests for TWO-STEP flows
- Security tests for authorization
- Load tests for concurrent requests
- 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 | 2026-01 | Initial published specification |
| 1.1.3 | 2026-03 | Added Intent Domain Router, Proactive Intelligence, 9-Level Context Model |
About the Author¶
Valentin Scerbacov is the creator of ICNLI, Webbee, WebHostMost, and Blue Bee Web. This specification was developed based on years of practical experience building AI-powered operational systems across commercial and enterprise domains. Webbee — the first production ICNLI implementation — runs live on WebHostMost today.
ICNLI represents a new approach to human-infrastructure interaction, combining natural language understanding with deep contextual awareness.
License¶
© 2026 Valentin Scerbacov / Imperal, Inc.
This specification is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0). You are free to share and adapt this material for any purpose, including commercial, under the terms of attribution and share-alike.
Full license: https://creativecommons.org/licenses/by-sa/4.0/
ICNLI™ is a registered trademark of Imperal, Inc. The CC BY-SA 4.0 license applies to the content of this specification but does not grant rights to use the ICNLI trademark for branding or commercial purposes without written permission. Webbee™ is a trademark of WebHostMost.
- Creator: Valentin Scerbacov
- Creator of: ICNLI, Webbee, WebHostMost, Blue Bee Web
- Trademark Owner: Imperal, Inc.
- Website: icnli.org
- Trademark inquiries: license@icnli.org
- First production implementation: Webbee — live at webhostmost.com
Unauthorized use, reproduction, or distribution of this specification or any portion thereof may result in civil and criminal penalties.
END OF SPECIFICATION