🛡️ SlavkoShell 2.0 – Routing & Security Layer

Zero-trust gateway that routes deterministically.

📜 Philosophy

The Shell guarantees protocol safety, strict schema validation, and deterministic routing. It never “guesses” – it hashes the input and always selects the same downstream pipeline.

Core Principles

1. Zero-Trust Architecture: Verify everything, trust nothing
   
2. Deterministic Routing: Same input → same model selection
   
3. Schema Validation: Strict JSON schema enforcement
   
4. Audit Checkpoint: First checkpoint in the audit chain
   
5. Plugin System: Extensible pre/post-routing hooks
   

✨ Core Features

📦 Installation

git clone https://github.com/FormatDisc/slavko-shell
cd slavko-shell
pip install -e .

Dependencies

python>=3.11
jsonschema>=4.17.0
pydantic>=2.0.0
cryptography>=41.0.0

🚀 Quick Start

from slavko_shell import Router
import json

router = Router()

payload = {
    "text": "Explain risk of secret leakage in this code",
    "metadata": {
        "source": "code_review",
        "priority": "high"
    }
}

try:
    routed = router.route(payload)
    print(f"Selected model: {routed.model}")
    print(f"Route hash: {routed.hash}")

    output = routed.call()
    print(json.dumps(output, indent=2))

except ValidationError as e:
    print(f"Validation error: {e}")
except RoutingError as e:
    print(f"Routing error: {e}")

🔐 Security Checklist

• ✅ All outbound traffic goes through https://<OLLAMA_HOST>/api/generate
  
• ✅ No environment variables leaked
  
• ✅ Validated against Schema v2.1
  
• ✅ Malicious payloads rejected
  
• ✅ Rate limiting enabled
  
• ✅ Full audit logging
  

📋 Configuration

Basic Configuration

from slavko_shell import Router, Config

config = Config(
    ollama_host="http://localhost:11434",
    default_model="qwen2.5:14b",
    rate_limit=100,
    timeout=30,
    enable_audit=True
)

router = Router(config=config)

Routing Table

from slavko_shell import Router, RoutingRule

routing_rules = [
    RoutingRule(
        condition=lambda payload: "image" in payload,
        model="phi3-vision",
        priority=10
    ),
    RoutingRule(
        condition=lambda payload: "pdf" in payload,
        model="qwen2.5:14b",
        priority=5
    ),
    RoutingRule(
        condition=lambda payload: payload.get("priority") == "high",
        model="deepseek-r1",
        priority=1
    )
]

router = Router(routing_rules=routing_rules)

🔍 Schema Validation

Input Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SlavkoShell Input Schema",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 100000
    },
    "image_base64": {
      "type": "string",
      "format": "base64"
    },
    "pdf_base64": {
      "type": "string",
      "format": "base64"
    },
    "search_query": {
      "type": "string",
      "maxLength": 500
    },
    "metadata": {
      "type": "object",
      "properties": {
        "source": { "type": "string" },
        "priority": {
          "type": "string",
          "enum": ["low", "medium", "high"]
        },
        "user_id": { "type": "string" }
      }
    }
  },
  "required": ["text"],
  "additionalProperties": false
}

Validation Example

from slavko_shell import Router, ValidationError

router = Router()

valid_payload = {
    "text": "Review this content",
    "metadata": {
        "source": "api",
        "priority": "medium"
    }
}

invalid_payload = {
    "metadata": {
        "source": "api"
    }
}

router.validate(valid_payload)

try:
    router.validate(invalid_payload)
except ValidationError as e:
    print(f"✗ Invalid: {e}")

🔧 Plugin System

Pre-Routing Hook

from slavko_shell import Router, Plugin
from datetime import datetime

class AuditPlugin(Plugin):
    def pre_route(self, payload: dict) -> dict:
        print(f"Routing request: {payload.get('text', '')[:50]}...")
        return payload
    
    def post_route(self, result: dict) -> dict:
        result["custom_metadata"] = {
            "processed_by": "AuditPlugin",
            "timestamp": datetime.now().isoformat()
        }
        return result

router = Router()
router.register_plugin(AuditPlugin())

Rate Limiting Plugin

from slavko_shell import Router, Plugin
from collections import defaultdict
import time

class RateLimitPlugin(Plugin):
    def __init__(self, max_requests: int = 100, window: int = 60):
        self.max_requests = max_requests
        self.window = window
        self.requests = defaultdict(list)
    
    def pre_route(self, payload: dict) -> dict:
        user_id = payload.get("metadata", {}).get("user_id", "anonymous")
        now = time.time()
        
        self.requests[user_id] = [
            t for t in self.requests[user_id]
            if now - t < self.window
        ]
        
        if len(self.requests[user_id]) >= self.max_requests:
            raise RateLimitError(f"Rate limit exceeded for {user_id}")
        
        self.requests[user_id].append(now)
        return payload

router = Router()
router.register_plugin(RateLimitPlugin(max_requests=50))

📊 Deterministic Routing

from slavko_shell import Router

router = Router()

payload1 = {"text": "Review this code", "metadata": {"priority": "high"}}
payload2 = {"text": "Review this code", "metadata": {"priority": "high"}}

route1 = router.route(payload1)
route2 = router.route(payload2)

assert route1.hash == route2.hash
assert route1.model == route2.model

🔐 Zero-Trust Networking

Dockerfile

FROM python:3.11-slim
RUN pip install --no-cache-dir slavko-shell
RUN useradd -m -u 1000 slavko
USER slavko
EXPOSE 8000
CMD ["python", "-m", "slavko_shell.api", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

version: '3.8'
services:
  shell:
    image: slavko-shell:latest
    networks:
      - internal
    environment:
      - OLLAMA_HOST=http://ollama:11434
      - NETWORK_MODE=isolated

  ollama:
    image: ollama/ollama:latest
    networks:
      - internal

networks:
  internal:
    driver: bridge
    internal: true


## 📈 Performance

| Metric | Value |
|--------|-------|
| **Routing latency** | ~0.3 ms |
| **Validation latency** | ~0.5 ms |
| **Memory** | ~10 MB |
| **Throughput** | > 5,000 req/sec |
| **CPU Usage** | < 1% per request |

## 🔍 Audit Trail


from slavko_shell import Router

router = Router(enable_audit=True)

payload = {"text": "Test request"}
route = router.route(payload)

audit_record = route.audit_record

## 🧪 Testing


pytest tests/test_shell.py -v
pytest tests/integration/test_shell_integration.py -v
pytest tests/security/test_shell_security.py -v

📞 Contact — Formatdisc

Company: Formatdisc – Computer Programming & Advanced Software Systems
Founder & System Architect: Mladen Gertner
Website: https://formatdisc.hr
Email: mladen@formatdisc.hr
Phone: +385 91 542 1014
Location: Zagreb, Croatia
OIB: 18915075854

GitHub: https://github.com/FormatDisc
LinkedIn: https://linkedin.com/company/formatdisc

From Code to Governance — One Shell, One Route, Zero Trust.