L1↔L2 Contract: Noosphere ↔ Orchestration

Canonical specification for communication between Noosphere Layer (L1) and Orchestration Layer (L2).

Overview

Purpose: Enable Orchestration (L2) to query Noosphere (L1) for semantic search, knowledge retrieval, and AI agent assistance.

Direction: Bidirectional

L2 → L1: Search requests from Orchestration to Noosphere
L1 → L2: Search results and knowledge from Noosphere to Orchestration

Transport: HTTP REST API with JSON payloads

Request Contract: L2 → L1

noosphere_search_request.v0

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mnemoverse.dev/schemas/noosphere_search_request.v0.json",
  "title": "noosphere_search_request.v0",
  "type": "object",
  "required": ["request_id", "query", "search_type", "max_results", "deadline_ms", "privacy_mode"],
  "properties": {
    "request_id": { "type": "string" },
    "query": { "type": "string", "minLength": 1 },
    "search_type": { "type": "string", "enum": ["vector", "graph", "hybrid", "ai_agent"] },
    "max_results": { "type": "integer", "minimum": 1, "maximum": 100 },
    "deadline_ms": { "type": "integer", "minimum": 100 },
    "quality_threshold": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
    "privacy_mode": { "type": "string", "enum": ["allow", "redact", "block"] },
    "context": {
      "type": "object",
      "properties": {
        "user_id": { "type": "string" },
        "session_id": { "type": "string" },
        "domain": { "type": "string", "enum": ["code", "documentation", "research", "general"] },
        "entities": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

AI Agent Request Extension

json

{
  "agent_request": {
    "type": "object",
    "properties": {
      "agent_type": { "type": "string", "enum": ["librarian", "researcher", "validator", "navigator"] },
      "task_type": { "type": "string" },
      "parameters": { "type": "object" }
    },
    "required": ["agent_type", "task_type"],
    "additionalProperties": false
  }
}

Request Examples

Vector Search Request:

json

{
  "request_id": "req_noosphere_001",
  "query": "How to implement JWT authentication in Node.js?",
  "search_type": "vector",
  "max_results": 10,
  "deadline_ms": 3000,
  "quality_threshold": 0.75,
  "privacy_mode": "redact",
  "context": {
    "user_id": "user_123",
    "session_id": "session_456",
    "domain": "code",
    "entities": ["jwt", "authentication", "nodejs"]
  }
}

AI Librarian Request:

json

{
  "request_id": "req_noosphere_002",
  "query": "Find comprehensive resources about transformer architectures",
  "search_type": "ai_agent",
  "max_results": 15,
  "deadline_ms": 5000,
  "quality_threshold": 0.8,
  "privacy_mode": "allow",
  "agent_request": {
    "agent_type": "librarian",
    "task_type": "discover",
    "parameters": {
      "domain": "research",
      "citation_style": "apa"
    }
  }
}

Response Contract: L1 → L2

noosphere_search_response.v0

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mnemoverse.dev/schemas/noosphere_search_response.v0.json",
  "title": "noosphere_search_response.v0",
  "type": "object",
  "required": ["request_id", "results", "metadata"],
  "properties": {
    "request_id": { "type": "string" },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "title", "content", "relevance_score", "source_type", "cost_tokens"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "content": { "type": "string" },
          "relevance_score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
          "source_type": { "type": "string", "enum": ["document", "concept", "code", "graph_node"] },
          "cost_tokens": { "type": "integer", "minimum": 0 },
          "metadata": {
            "type": "object",
            "properties": {
              "url": { "type": "string" },
              "authors": { "type": "array", "items": { "type": "string" } },
              "publication_date": { "type": "string", "format": "date" },
              "entities": { "type": "array", "items": { "type": "string" } },
              "quality_signals": {
                "type": "object",
                "properties": {
                  "citations": { "type": "integer", "minimum": 0 },
                  "credibility": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
                  "recency": { "type": "number", "minimum": 0.0, "maximum": 1.0 }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    },
    "metadata": {
      "type": "object",
      "required": ["total_results", "search_method", "latency_ms"],
      "properties": {
        "total_results": { "type": "integer", "minimum": 0 },
        "search_method": { "type": "string", "enum": ["vector", "graph", "hybrid", "ai_agent"] },
        "latency_ms": { "type": "integer", "minimum": 0 },
        "quality_achieved": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
        "cost_breakdown": {
          "type": "object",
          "properties": {
            "search_tokens": { "type": "integer", "minimum": 0 },
            "agent_tokens": { "type": "integer", "minimum": 0 },
            "total_cost_cents": { "type": "number", "minimum": 0 }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "string", "enum": ["PARTIAL_RESULTS", "LOW_QUALITY", "TIMEOUT_RISK", "PRIVACY_REDACTED"] },
          "message": { "type": "string" },
          "impact": { "type": "string", "enum": ["low", "medium", "high"] }
        },
        "additionalProperties": false
      }
    },
    "error": {
      "type": "object",
      "required": ["code", "message", "retriable"],
      "properties": {
        "code": { "type": "string", "enum": ["QUERY_INVALID", "TIMEOUT", "SYSTEM_ERROR", "CAPACITY_EXCEEDED"] },
        "message": { "type": "string" },
        "retriable": { "type": "boolean" },
        "retry_after_ms": { "type": "integer", "minimum": 0 }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Response Examples

Successful Vector Search Response:

json

{
  "request_id": "req_noosphere_001",
  "results": [
    {
      "id": "doc_jwt_auth_001",
      "title": "JWT Authentication Implementation Guide",
      "content": "JSON Web Tokens (JWT) provide a compact way to securely transmit information...",
      "relevance_score": 0.92,
      "source_type": "document",
      "cost_tokens": 150,
      "metadata": {
        "url": "https://auth0.com/learn/json-web-tokens",
        "authors": ["Auth0 Team"],
        "publication_date": "2023-08-15",
        "entities": ["jwt", "authentication", "nodejs", "security"],
        "quality_signals": {
          "citations": 245,
          "credibility": 0.89,
          "recency": 0.85
        }
      }
    },
    {
      "id": "code_jwt_example_002",
      "title": "Node.js JWT Middleware Example",
      "content": "const jwt = require('jsonwebtoken');\n\nfunction authenticateToken(req, res, next) {\n  const authHeader = req.headers['authorization'];\n  const token = authHeader && authHeader.split(' ')[1];\n\n  if (token == null) return res.sendStatus(401);\n\n  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {\n    if (err) return res.sendStatus(403);\n    req.user = user;\n    next();\n  });\n}",
      "relevance_score": 0.87,
      "source_type": "code",
      "cost_tokens": 200,
      "metadata": {
        "url": "https://github.com/example/jwt-middleware",
        "entities": ["jwt", "middleware", "nodejs", "express"],
        "quality_signals": {
          "citations": 0,
          "credibility": 0.75,
          "recency": 0.92
        }
      }
    }
  ],
  "metadata": {
    "total_results": 2,
    "search_method": "vector",
    "latency_ms": 1250,
    "quality_achieved": 0.89,
    "cost_breakdown": {
      "search_tokens": 350,
      "agent_tokens": 0,
      "total_cost_cents": 1.75
    }
  }
}

AI Agent Response:

json

{
  "request_id": "req_noosphere_002",
  "results": [
    {
      "id": "agent_summary_001",
      "title": "Transformer Architecture Research Summary",
      "content": "Based on my analysis of 45 papers, transformers represent a paradigm shift...",
      "relevance_score": 0.95,
      "source_type": "document",
      "cost_tokens": 500,
      "metadata": {
        "authors": ["AI Librarian"],
        "entities": ["transformers", "attention", "neural networks"],
        "quality_signals": {
          "citations": 0,
          "credibility": 0.88,
          "recency": 1.0
        }
      }
    }
  ],
  "metadata": {
    "total_results": 1,
    "search_method": "ai_agent",
    "latency_ms": 4200,
    "quality_achieved": 0.95,
    "cost_breakdown": {
      "search_tokens": 200,
      "agent_tokens": 800,
      "total_cost_cents": 12.5
    }
  }
}

Error Response:

json

{
  "request_id": "req_noosphere_003",
  "results": [],
  "metadata": {
    "total_results": 0,
    "search_method": "vector",
    "latency_ms": 3000
  },
  "error": {
    "code": "TIMEOUT",
    "message": "Search operation exceeded deadline of 3000ms",
    "retriable": true,
    "retry_after_ms": 1000
  }
}

HTTP API Specification

Base URL

https://noosphere.mnemoverse.dev/api/v0

Endpoints

POST /search

Execute search query against Noosphere layer.

Request:

Method: POST
Path: /search
Headers:
- Content-Type: application/json
- Authorization: Bearer {api_key}
Body: noosphere_search_request.v0

Response:

Status: 200 OK | 400 Bad Request | 500 Internal Server Error | 503 Service Unavailable
Headers:
- Content-Type: application/json
- X-Request-ID: {request_id}
Body: noosphere_search_response.v0

GET /health

Health check endpoint.

Response:

json

{
  "status": "healthy",
  "components": {
    "vector_search": "healthy",
    "knowledge_graph": "healthy", 
    "ai_agents": "healthy",
    "hyperbolic_engine": "degraded"
  },
  "timestamp": "2025-09-06T10:00:00Z"
}

Error Handling

Standard Error Codes:

QUERY_INVALID: Malformed query or invalid parameters
TIMEOUT: Operation exceeded deadline
SYSTEM_ERROR: Internal system failure
CAPACITY_EXCEEDED: System at capacity, retry later

HTTP Status Mappings:

QUERY_INVALID → 400 Bad Request
TIMEOUT → 504 Gateway Timeout
SYSTEM_ERROR → 500 Internal Server Error
CAPACITY_EXCEEDED → 503 Service Unavailable

Performance Characteristics

SLA Targets

Availability: 99.5% uptime
Latency: P95 < 3 seconds for vector search, P95 < 8 seconds for AI agents
Throughput: 100 requests/second per instance
Quality: Average relevance score > 0.8

Rate Limiting

Default: 1000 requests/hour per API key
Burst: 10 requests/second
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Integration Examples

Orchestration → Noosphere Search

typescript

// L2 (Orchestration) calling L1 (Noosphere)
class NoosphereClient {
  async search(query: string, context: SearchContext): Promise<NoosphereResults> {
    const request: NoosphereSearchRequest = {
      request_id: uuidv4(),
      query,
      search_type: "hybrid",
      max_results: 15,
      deadline_ms: 5000,
      quality_threshold: 0.8,
      privacy_mode: context.privacy_mode || "redact",
      context: {
        user_id: context.user_id,
        domain: context.domain,
        entities: context.entities
      }
    };

    const response = await fetch(`${this.baseUrl}/search`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`
      },
      body: JSON.stringify(request)
    });

    if (!response.ok) {
      throw new Error(`Noosphere search failed: ${response.statusText}`);
    }

    return response.json();
  }
}

Status: Canonical specification ready for implementation Schema Location: /architecture/contracts/schemas/noosphere_*.v0.json (to be created)

ACS

API

CEO

HCS

Implementation

L1↔L2 Contract: Noosphere ↔ Orchestration ​

Overview ​

Request Contract: L2 → L1 ​

noosphere_search_request.v0 ​

AI Agent Request Extension ​

Request Examples ​

Response Contract: L1 → L2 ​

noosphere_search_response.v0 ​

Response Examples ​

HTTP API Specification ​

Base URL ​

Endpoints ​

POST /search ​

GET /health ​

Error Handling ​

Performance Characteristics ​

SLA Targets ​

Rate Limiting ​

Integration Examples ​

Orchestration → Noosphere Search ​

L1↔L2 Contract: Noosphere ↔ Orchestration

Overview

Request Contract: L2 → L1

noosphere_search_request.v0

AI Agent Request Extension

Request Examples

Response Contract: L1 → L2

noosphere_search_response.v0

Response Examples

HTTP API Specification

Base URL

Endpoints

POST /search

GET /health

Error Handling

Performance Characteristics

SLA Targets

Rate Limiting

Integration Examples

Orchestration → Noosphere Search