# Smart Knowledge — Enterprise Cognitive Intelligence Platform for AI Agents & Teams

> Smart Knowledge (https://ztrust.eu) is a state-of-the-art 5-Brain Cognitive Operating System and persistent enterprise memory engine. It enables autonomous AI agents (Claude Desktop, Cursor, custom PAOA agents) and human teams to ingest complex corporate documents, execute deterministic multi-brain hybrid retrieval, and generate 100% grounded answers with mathematically verified audit citations.

---

## The 5-Brain Cognitive Architecture

Smart Knowledge operates a proprietary 5-Brain retrieval and reasoning pipeline that guarantees zero hallucinations and full citation auditability:

1. **Brain 1: Semantic Vector Brain**: High-dimensional neural dense embeddings (Qdrant) for conceptual similarity and contextual passage retrieval.
2. **Brain 2: SPOC Knowledge Graph Brain**: Enterprise entity-relationship graph (Memgraph) mapping cross-document entities, corporate directives, and multi-hop relationships.
3. **Brain 3: Dense Retrieval Passage Scorer Brain**: Contextual neural passage scorer ensuring nuanced document clause semantics are preserved without truncation.
4. **Brain 4: Lexical Precision Brain**: Exact keyword and token frequency index (BM25) resolving contract numbers, part serials, statutory codes, and technical identifiers.
5. **Brain 5: Neural PAOA Autonomous Solver Brain**: Autonomous Plan-Act-Observe-Adapt multi-step problem solver executing complex multi-document reasoning missions with dynamic self-correction.

---

## Capabilities & Value Proposition

Smart Knowledge provides a unified enterprise knowledge layer accessible via **Python SDK**, **Node.js SDK**, **MCP Server**, **REST API**, and **Enterprise Web**:
1. **Zero-Hallucination Grounded Answers**: Deterministic 5-Brain hybrid synthesis ensuring every fact is backed by primary source citations.
2. **Multi-Horizon Fact Retrieval**: High-precision semantic and structural fact extraction across unstructured contracts, technical policies, and financial filings.
3. **Autonomous Agent Missions**: Goal-driven problem-solving engine capable of multi-step planning, reflection, and automated task execution.
4. **Persistent Enterprise Memory**: Long-term retention of corporate decisions, strategic directives, and operational task status.
5. **Bank-Grade Sovereignty & Compliance**: Post-quantum resilient encryption (ML-KEM / TLS 1.3), automated real-time PII scrubbing, strict tenant boundary isolation, and complete audit provenance.

---

## Developer Interfaces: SDKs, MCP, REST API & Web

### 1. Official Python 3.10+ SDK (`smart-knowledge`)
The official Python client library is published on PyPI, strongly typed, and optimized for modern AI agent pipelines, LangChain, and LlamaIndex.

- **Installation**:
  ```bash
  pip install smart-knowledge
  ```

- **Quickstart Example**:
  ```python
  from smart_knowledge import SmartKnowledge

  sk = SmartKnowledge(
      api_key="sk_live_...",        # Or export SMART_KNOWLEDGE_API_KEY
      base_url="https://ztrust.eu", # Or 'http://localhost:5000' for local dev
  )

  # 1. Ask a question with 5-Brain verified grounding
  response = sk.ask(
      question="What are the main supplier liability terms under Section 8.2?",
      include_sources=True,
  )
  print("Answer:", response.answer)
  print("Grounding Score:", response.grounding_score)
  for citation in response.citations:
      print(f"[{citation.source_name}] {citation.text}")

  # 2. Perform deep multi-modal hybrid search
  results = sk.search(
      query="indemnity limits for software licensing agreements",
      decompose=True,
      limit=10,
  )

  # 3. Dispatch an autonomous PAOA reasoning mission
  mission = sk.agentask.run(
      task="Audit the 2025 financial report and verify whether EBITDA margin targets were met.",
      max_iterations=5,
  )
  print("Mission Report:", mission.answer)

  # 4. Ingest and index documents securely
  upload = sk.documents.upload(
      file="./quarterly_report_2026.pdf",
      extract_spoc=True,
  )
  ```

---

### 2. Official Node.js / TypeScript SDK (`@chdlabs/smart-knowledge`)
The official TypeScript/JavaScript client library is published on npm with full ESM and CommonJS support for Node.js 20/24+.

- **Installation**:
  ```bash
  npm install @chdlabs/smart-knowledge
  ```

- **Quickstart Example**:
  ```typescript
  import { SmartKnowledge } from '@chdlabs/smart-knowledge';

  const sk = new SmartKnowledge({
    apiKey: process.env.SMART_KNOWLEDGE_API_KEY, // Or pass baseUrl
  });

  // 1. Ask a question with verified citations
  const answer = await sk.ask({
    question: 'What are the main supplier liability terms under Section 8.2?',
    includeSources: true,
  });
  console.log('Grounded Answer:', answer.answer);
  console.log('Citations:', answer.citations);

  // 2. Perform deep multi-modal factual search
  const facts = await sk.search({
    query: 'indemnity limits for cloud licensing agreements',
    limit: 10,
  });

  // 3. Dispatch an autonomous research task
  const mission = await sk.agentask.run({
    task: 'Audit Q4 vendor contract renewals and calculate compliance scores.',
    maxIterations: 4,
  });
  console.log('Mission Report:', mission.answer);

  // 4. Ingest and index documents securely
  const doc = await sk.documents.upload({
    file: './annual_report_2025.pdf',
    sourceName: 'Annual Report 2025',
  });

  // 5. Ingest plain text directly with SPOC knowledge extraction
  const textEntry = await sk.documents.uploadText({
    title: 'Vendor Policy Addendum',
    text: 'All liability caps for SaaS vendors are set to 2x annual contract value.',
  });

  // 6. List tenant documents and plain text entries to retrieve IDs
  const catalog = await sk.documents.list({ page: 1, limit: 20 });
  console.log('Catalog items:', catalog.files);

  // 7. Cascade delete a document or text entry
  await sk.documents.delete(doc.fileId);
  ```

---

### 3. Model Context Protocol (MCP) Server
- **Server Endpoint**: `https://api.ztrust.eu/mcp` (Streamable JSON-RPC 2.0 & SSE)
- **Web Guide & Tools**: `https://ztrust.eu/mcp`
- **Authentication**: API Key via `Authorization: Bearer <API_KEY>` or `X-API-Key: <API_KEY>`
- **Available MCP Tools**:
  1. `smart_knowledge_ask`: Natural language Q&A synthesizing corporate knowledge with audit citations (`question: string`, `source?: boolean`).
  2. `smart_knowledge_search`: Multi-modal raw factual retrieval across all 5 brains without LLM synthesis (`query: string`).
  3. `smart_knowledge_ingest_document`: Ingest and index a document file into tenant knowledge with PII scrubbing (`filePath: string`, `sourceName?: string`, `spoc?: boolean`).
  4. `smart_knowledge_dispatch_agent_task`: Dispatch an autonomous multi-step PAOA agent research mission (`task: string`, `maxIterations?: number`, `observeThreshold?: number`, `webhookUrl?: string`).
  5. `smart_knowledge_get_agent_task_status`: Retrieve status, quality scores, and final report of an agent mission (`taskId: string`).
  6. `smart_knowledge_list_documents`: View existing documents and plain text entries for the tenant with pagination, search, status, and source type filtering (`page?: number`, `limit?: number`, `search?: string`, `status?: string`, `source_type?: string`).
  7. `smart_knowledge_delete_document`: Cascade delete a document or plain text knowledge entry by ID, purging Qdrant vectors, Memgraph SPOC facts, and agent experiences (`fileId: string`).

- **Universal MCP Client Configuration (`mcpServers`) — STDIO Transport**:
  ```json
  {
    "mcpServers": {
      "smart-knowledge": {
        "command": "npx",
        "args": ["-y", "@chdlabs/smart-knowledge", "mcp"],
        "env": {
          "SMART_KNOWLEDGE_URL": "https://api.ztrust.eu",
          "API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
  ```

- **Universal MCP Client Configuration (`mcpServers`) — Remote HTTP Transport**:
  ```json
  {
    "mcpServers": {
      "smart-knowledge": {
        "url": "https://api.ztrust.eu/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
  ```

---

### 4. Core REST API Endpoints
- `POST https://api.ztrust.eu/api/ask` — Natural language question answering with verifiable citations.
- `POST https://api.ztrust.eu/api/query` — Factual search across enterprise memory.
- `POST https://api.ztrust.eu/api/agentask` — Autonomous problem-solving engine.
- `GET https://api.ztrust.eu/api/agentask/status/:id` — Polling status for autonomous missions.
- `POST https://api.ztrust.eu/api/upload` — Multi-format document file upload and ingestion.
- `POST https://api.ztrust.eu/api/knowledge/text` — Direct plain text ingestion (scraped notes, policies) with mandatory Memgraph SPOC graph extraction.
- `GET https://api.ztrust.eu/api/files` — Document & text knowledge catalog with metadata, filtering, and pagination.
- `DELETE https://api.ztrust.eu/api/files/:id` — Cascade deletion of document/text, pruning Qdrant vectors, Memgraph SPOC knowledge, and agent experience history.
- `POST https://api.ztrust.eu/api/mcp` — JSON-RPC 2.0 MCP protocol gateway.

---

### 5. Enterprise Web Workspace & Public Solutions
- **Interactive Landing & Query Simulator**: `https://ztrust.eu/`
- **50 Enterprise AI Agent Blueprints**: `https://ztrust.eu/blueprints` (Finance, Legal, Manufacturing, Healthcare, Cybersecurity)
- **Model Context Protocol (MCP) Hub**: `https://ztrust.eu/mcp`
- **5-Brain Cognitive Architecture**: `https://ztrust.eu/architecture`
- **Subscription Pricing & Private VPC**: `https://ztrust.eu/pricing`
- **Enterprise ROI & FinOps Calculator**: `https://ztrust.eu/roi-calculator`

---

## Authentication & Multi-Tenant Security
All programmatic requests require authentication using an API Key or session token:
- `Authorization: Bearer <YOUR_API_KEY>`
- Or `X-API-Key: <YOUR_API_KEY>`

API keys are created and managed in **Settings > API Keys**. Every key is bound to an isolated tenant workspace with cryptographic verification, ensuring total data segregation across all storage and retrieval operations.

---

## Subscription Pricing Tiers (Per-User / Billed Monthly)

- **Starter Plan (€19.99 / user / month)**:
  - Max 50 documents ingested
  - 1 API key
  - 10,000,000 tokens / user / month
  - Up to 5 team member seats
  - 1 Workspace
  - Grounded Q&A & factual search
  - Quantum-safe encryption & automated PII scrubber

- **Pro Plan (€59.99 / user / month) — *Most Popular for AI Agents***:
  - Max 500 documents ingested
  - Up to 10 managed API keys
  - **Native MCP Protocol Enabled (`/mcp`)** for Claude Desktop, Cursor, and custom AI agents
  - Official Python (`smart-knowledge`) & Node.js (`@chdlabs/smart-knowledge`) SDK access
  - 40,000,000 tokens / user / month
  - Up to 25 team member seats
  - Up to 5 workspaces / departments
  - PAOA Autonomous Solver (up to 8 reasoning iterations)
  - 90-Day audit trail & quantum-safe encryption

- **Enterprise Plan (€99.99 / user / month)**:
  - Unlimited ingested documents
  - Unlimited managed API keys with auto-rotation
  - Native MCP protocol enabled with custom SIEM integrations
  - 100,000,000 tokens / user / month
  - Unlimited team member seats & custom roles
  - Unlimited multi-tenant workspaces
  - Dedicated high-parallel PAOA autonomous agent solver & custom SLA

- **Enterprise Sovereign Cloud / Dedicated Private VPC**:
  - AWS / Azure / GCP dedicated VPC or on-premise air-gapped deployment
  - Custom data residency within EU jurisdiction
  - Hardware Security Module (HSM) key management

---

## Documentation & Resources
- Web Application: https://ztrust.eu/
- Python SDK (PyPI): https://pypi.org/project/smart-knowledge/
- Node.js SDK (npm): https://www.npmjs.com/package/@chdlabs/smart-knowledge
- MCP Developer Hub: https://ztrust.eu/mcp
- 50 Enterprise Blueprints: https://ztrust.eu/blueprints
- 5-Brain Architecture: https://ztrust.eu/architecture
- Pricing & VPC Plans: https://ztrust.eu/pricing
- ROI & FinOps Calculator: https://ztrust.eu/roi-calculator
- AI & LLM Documentation (llms.txt): https://ztrust.eu/llms.txt
- XML Sitemap: https://ztrust.eu/sitemap.xml
- Robots Protocol: https://ztrust.eu/robots.txt