qilbee-mycelial-network 0.2.0

Enterprise SaaS SDK for Qilbee Mycelial Network - Adaptive AI Agent Communication

Qilbee Mycelial Network (QMN) - Python SDK

Enterprise SaaS SDK for building adaptive AI agent communication networks inspired by biological mycelia. Enable your AI agents to form a self-optimizing communication network with automatic reinforcement learning and emergent collective intelligence.

🌟 Why Qilbee Mycelial Network?

Traditional AI agent systems struggle with:

• Static routing - Hard-coded communication patterns that don't adapt
• Context isolation - Agents can't share learned knowledge effectively
• Scalability - Infrastructure complexity grows with agent count
• No learning - Systems don't improve from past interactions

Qilbee solves these problems by creating a living network where:

• 🧠 Agents share context through semantic embeddings
• 📈 Routes strengthen based on successful outcomes
• 🔄 Network topology evolves automatically
• ☁️ Zero infrastructure management required

🚀 Quick Start

Installation

pip install qilbee-mycelial-network

For additional transport protocols:

# gRPC support (high performance)
pip install qilbee-mycelial-network[grpc]

# QUIC support (low latency)
pip install qilbee-mycelial-network[quic]

# OpenTelemetry integration
pip install qilbee-mycelial-network[telemetry]

# Everything
pip install qilbee-mycelial-network[all]

Basic Usage

import asyncio
from qilbee_mycelial_network import MycelialClient, Nutrient, Outcome, Sensitivity

async def main():
    # Initialize client (reads QMN_API_KEY from environment)
    async with MycelialClient.create_from_env() as client:

        # Broadcast nutrient to network
        await client.broadcast(
            Nutrient.seed(
                summary="Need PostgreSQL performance optimization advice",
                embedding=[...],  # Your 1536-dim embedding vector
                snippets=["EXPLAIN ANALYZE output..."],
                tool_hints=["db.analyze", "query.optimize"],
                sensitivity=Sensitivity.INTERNAL,
                ttl_sec=180,
                max_hops=3
            )
        )

        # Collect enriched contexts from network
        contexts = await client.collect(
            demand_embedding=[...],  # Your query embedding
            window_ms=300,
            top_k=5,
            diversify=True  # Apply MMR diversity
        )

        # Use collected context...
        for content in contexts.contents:
            print(f"Agent: {content['agent_id']}")
            print(f"Response: {content['data']}")

        # Record outcome for reinforcement learning
        await client.record_outcome(
            trace_id=contexts.trace_id,
            outcome=Outcome.with_score(0.92)  # 0.0 to 1.0
        )

asyncio.run(main())

📋 Core Features

🔄 Adaptive Routing

Routes are selected based on:

• Embedding similarity - Cosine similarity between nutrient and agent profiles
• Learned weights - Connection strengths that evolve (0.01 to 1.5)
• Historical success - Reinforcement learning from task outcomes
• Capability matching - Tool/skill alignment
• Diversity - Maximum Marginal Relevance for varied results

🧠 Vector Memory

• Distributed storage with PostgreSQL + pgvector
• Semantic search across all agent contexts
• 1536-dimension embeddings (OpenAI compatible)
• Automatic indexing and optimization

🛡️ Enterprise Security

• Encryption: TLS 1.3 in transit, AES-256-GCM at rest
• DLP: 4-tier sensitivity labels (PUBLIC/INTERNAL/CONFIDENTIAL/SECRET)
• RBAC: Role-based access control
• Audit trail: Ed25519 signed events
• Multi-tenancy: Row-level security isolation
• Compliance: SOC 2, ISO 27001 ready

🌍 Multi-Region

• Automatic failover and disaster recovery
• Regional routing based on proximity
• Global replication with eventual consistency
• 99.99% availability SLO

📊 Full Observability

• Prometheus metrics - Latency, throughput, error rates
• Distributed tracing - OpenTelemetry integration
• Grafana dashboards - Pre-built visualizations
• Health checks - Liveness and readiness probes

🔧 Configuration

Environment Variables

# Required
export QMN_API_KEY=qmn_your_api_key_here

# Optional
export QMN_API_BASE_URL=https://api.qilbee.io      # API endpoint
export QMN_PREFERRED_REGION=us-east-1              # Preferred region
export QMN_TRANSPORT=grpc                          # grpc, quic, or http
export QMN_DEBUG=true                              # Enable debug logging
export QMN_TIMEOUT_SEC=30                          # Request timeout
export QMN_MAX_RETRIES=3                           # Retry attempts

Programmatic Configuration

from qilbee_mycelial_network import MycelialClient, QMNSettings

settings = QMNSettings(
    api_key="qmn_your_key",
    api_base_url="https://api.qilbee.io",
    preferred_region="us-west-2",
    transport="grpc",
    timeout_sec=30,
    max_retries=3,
    debug=False
)

async with MycelialClient(settings) as client:
    # Your code here
    pass

📖 Advanced Examples

Example 1: Multi-Agent Collaboration

import asyncio
from qilbee_mycelial_network import MycelialClient, Nutrient, Sensitivity

async def collaborative_task():
    async with MycelialClient.create_from_env() as client:
        # Agent 1: Research agent shares findings
        await client.broadcast(
            Nutrient.seed(
                summary="Found vulnerability in auth module",
                embedding=get_embedding("security vulnerability authentication"),
                snippets=["CVE-2024-1234", "Affects version 2.3.1"],
                tool_hints=["security.scan", "code.review"],
                sensitivity=Sensitivity.CONFIDENTIAL
            )
        )

        # Agent 2: Security agent queries for relevant context
        contexts = await client.collect(
            demand_embedding=get_embedding("security issues authentication"),
            top_k=10,
            diversify=True
        )

        # Agent processes contexts and takes action
        for ctx in contexts.contents:
            print(f"Found related issue: {ctx['summary']}")

        # Record successful collaboration
        await client.record_outcome(
            trace_id=contexts.trace_id,
            outcome=Outcome.with_score(0.95)
        )

Example 2: Learning from Outcomes

import asyncio
from qilbee_mycelial_network import MycelialClient, Outcome

async def learning_loop():
    async with MycelialClient.create_from_env() as client:
        # Collect contexts for a task
        contexts = await client.collect(
            demand_embedding=task_embedding,
            top_k=5
        )

        # Execute task with collected contexts
        result = await execute_task(contexts)

        # Record outcome - this strengthens successful routes
        if result.success:
            await client.record_outcome(
                trace_id=contexts.trace_id,
                outcome=Outcome.with_score(result.quality)  # 0.0 to 1.0
            )
        else:
            # Negative outcome weakens these routes
            await client.record_outcome(
                trace_id=contexts.trace_id,
                outcome=Outcome.with_score(0.0)
            )

Example 3: Custom Agent Profiles

from qilbee_mycelial_network import MycelialClient

async def register_agent():
    async with MycelialClient.create_from_env() as client:
        # Register agent with capabilities
        await client.register_agent(
            agent_id="code-reviewer-01",
            profile_embedding=get_embedding("code review security best practices"),
            capabilities=[
                "code.review",
                "security.audit",
                "performance.analyze"
            ],
            metadata={
                "languages": ["python", "javascript", "go"],
                "expertise": ["security", "performance"],
                "version": "2.0.1"
            }
        )

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     Client SDK                          │
│              (pip install qilbee-mycelial-network)      │
└─────────────────────────┬───────────────────────────────┘
                          │ HTTPS/gRPC/QUIC
                          ▼
┌─────────────────────────────────────────────────────────┐
│                  Control Plane                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
│  │ Identity │  │   Keys   │  │ Policies │               │
│  └──────────┘  └──────────┘  └──────────┘               │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                  Data Plane (Regional)                  │
│  ┌──────────┐  ┌────────────────┐  ┌────────────────┐   │
│  │  Router  │  │ Hyphal Memory  │  │ Reinforcement  │   │
│  │          │  │   (pgvector)   │  │    Engine      │   │
│  └──────────┘  └────────────────┘  └────────────────┘   │
└─────────────────────────────────────────────────────────┘

Routing Algorithm

Nutrients flow through the network based on:

1. Semantic Similarity (40% weight)

   • Cosine similarity between embeddings
   • Agent profile matching

2. Edge Weights (30% weight)

   • Learned from historical outcomes
   • Range: 0.01 to 1.5
   • Updated via reinforcement learning

3. Capability Match (20% weight)

   • Tool/skill alignment
   • Metadata filtering

4. Diversity (10% weight)

   • Maximum Marginal Relevance
   • Prevents echo chambers

Reinforcement Learning

Edge weights evolve using:

Δw = α_pos × outcome - α_neg × (1 - outcome) - λ_decay

Where:

• α_pos = 0.08 - Positive learning rate
• α_neg = 0.04 - Negative learning rate
• λ_decay = 0.002 - Natural decay to prevent stagnation
• outcome ∈ [0, 1] - Task success score

📊 Performance

Target SLOs:

• p95 single-hop routing: < 120ms
• p95 collect() end-to-end: < 350ms
• Throughput: 10,000 nutrients/min per node
• Regional availability: ≥ 99.99%

🧪 Testing

# Run all tests
pytest

# With coverage
pytest --cov=qilbee_mycelial_network --cov-report=html

# Integration tests only
pytest tests/integration/

# Performance benchmarks
pytest tests/performance/ -v

📚 Documentation

• Homepage: qilbee.io
• Full Documentation: qilbee.io/docs
• API Reference: API Docs
• Examples: GitHub Examples
• Architecture: System Design

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - Copyright (c) 2025 AICUBE TECHNOLOGY LLC

See LICENSE for details.

🔗 Links

• PyPI: pypi.org/project/qilbee-mycelial-network
• GitHub: github.com/aicubetechnology/qilbee-mycelial-network
• Issues: GitHub Issues
• Discussions: GitHub Discussions

💬 Support

• Email: [e-mail]
• GitHub Issues: Report a bug
• GitHub Discussions: Ask questions

---

Built with ❤️ by AICUBE TECHNOLOGY LLC

Inspired by the intelligence of fungal mycelial networks.