ghostmind-client 1.1.0

Ultra-lightweight client SDK for GhostBox.in - customer-controlled compliance validation

GhostMind Client SDK

Ultra-lightweight Python client for GhostMind server. You control your own LLM for Layers 1 & 4 (Intent + Explanation).

SaaS Platform

🚀 Managed Instances: Use the GhostMind SaaS Platform for instant AERM instance deployment

• ✅ Free tier available (1K API calls/month)
• ✅ Automatic instance provisioning
• ✅ API key authentication
• ✅ No infrastructure management

See: Instance Architecture Guide for how instances work with the SaaS platform.

Architecture

┌─────────────────────────────────────────────────────────┐
│                  GhostMind Client SDK                   │
│                  (Customer Machine)                      │
│                                                          │
│  Layer 1: Intent Parsing     ◄───── YOUR LLM           │
│  Layer 4: Explanation        ◄───── (Ollama/LM Studio) │
└─────────────────────────────────────────────────────────┘
                         │
                         │ HTTP API
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  GhostMind Server                       │
│                  (Your Infrastructure)                   │
│                                                          │
│  Layer 2: Fact Extraction    ◄───── Regex (NO LLM)     │
│  Layer 3: Physics Ranking    ◄───── Vector DB (NO LLM) │
└─────────────────────────────────────────────────────────┘

Key Design:

• Client controls LLM: You choose Ollama, LM Studio, OpenAI, Claude, or custom
• Server has NO LLM: Ultra-lightweight (<400MB RAM), zero hallucination risk
• Physics validation: Detects contradictions, prevents conflicts
• Privacy-first: Server only sees extracted facts, not raw text (optional)

Quick Start

1. Get Your AERM Instance

Using GhostMind SaaS Platform:

1. Sign up at https://ghostbox.in
2. Subscribe to a plan (Free tier available)
3. Your AERM instance will be automatically deployed
4. Go to API Keys page to generate an SDK token
5. Copy your SDK token (gm_sdk_...)

Or Self-Host:

• Deploy AERM server on your infrastructure
• See Self-Hosting Guide

2. Install

# From PyPI (coming soon)
pip install ghostmind-client

# From source
cd client-sdk
pip install -e .

3. Choose Your LLM

Option A: LM Studio (Recommended for beginners)

• ✅ Easy GUI interface
• ✅ One-click model downloads
• ✅ 100% local, privacy-first
• ✅ OpenAI-compatible API

See: LM Studio Guide

Option B: Ollama (Recommended for developers)

• ✅ Fast CLI-based setup
• ✅ Scriptable workflows
• ✅ Docker-friendly
• ✅ Great for production servers

Option C: Custom (Bring your own)

• Implement LLMAdapter interface
• Use OpenAI, Claude, Gemini, etc.

4. Connect in One Line! 🎉

NEW Simplified API (v1.1.0+):

import asyncio
from ghostmind_client import GhostMindClient
from ghostmind_client.llm import OllamaAdapter

async def main():
    # Just copy token from dashboard - that's it!
    client = await GhostMindClient.connect(
        llm=OllamaAdapter(model="llama2"),
        token="gm_sdk_abc123..."  # From dashboard
    )
    
    # Validate a query
    result = await client.validate(
        text="Can I schedule a meeting tomorrow at 3pm?",
        user_id="user123"
    )
    
    print(f"Decision: {result['action']}")

asyncio.run(main())

Features:

• ✅ No port numbers to remember
• ✅ No platform URLs to configure
• ✅ Environment auto-detection (production/beta)
• ✅ Session saving for instant reconnect

First-time with Email/Password:

# Connect with email (first time)
client = await GhostMindClient.connect(
    llm=OllamaAdapter(model="llama2"),
    email="[e-mail]",
    password="YourPassword"
)

# Save session for next time
saved_session = client.session
# Store `saved_session` securely

# Reconnect instantly (no login!)
client = await GhostMindClient.connect(
    llm=OllamaAdapter(model="llama2"),
    session=saved_session
)

Beta Environment:

# Test against beta environment
client = await GhostMindClient.connect(
    llm=OllamaAdapter(model="llama2"),
    token="gm_sdk_...",
    environment="beta"  # or "production" (default)
)

Environment Variables:

# Set in your shell
export GHOSTMIND_ENV=beta
export GHOSTMIND_TOKEN=gm_sdk_...

# Or use .env file

# Connect - reads from environment automatically
client = await GhostMindClient.connect(
    llm=OllamaAdapter(model="llama2"),
    token=os.getenv("GHOSTMIND_TOKEN")
)

5. Legacy API (Still Supported)

With GhostMind SaaS (Old Way):

import asyncio
from ghostmind_client import GhostMindClient
from ghostmind_client.llm import LMStudioAdapter

async def main():
    # Initialize LLM adapter (runs locally on your machine)
    llm = LMStudioAdapter(
        model="local-model",
        base_url="http://localhost:1234/v1"
    )
    
    # Initialize GhostMind client with SaaS instance
    client = GhostMindClient(
        api_url="https://aerm-user123.ghostbox.in",  # Your instance endpoint
        api_key="gm_your_api_key_here",              # From API Keys page
        llm_adapter=llm,
        domain="medical"
    )
    
    # Commit trusted facts
    await client.commit_fact(
        text="Patient is allergic to penicillin",
        user_id="patient_001",
        energy=0.95
    )
    
    # Validate query (4-layer validation)
    result = await client.validate(
        text="Can I take amoxicillin?",
        user_id="patient_001"
    )
    
    print(f"Action: {result['action']}")  # "REJECT"
    print(f"Reason: {result['reason']}")  # "Drug allergy conflict"
    print(f"Explanation: {result['explanation']}")  # LLM-generated explanation

asyncio.run(main())

Self-Hosted (No API key needed):

import asyncio
from ghostmind_client import GhostMindClient
from ghostmind_client.llm import LMStudioAdapter

async def main():
    # Initialize LLM adapter
    llm = LMStudioAdapter(
        model="local-model",
        base_url="http://localhost:1234/v1"
    )
    
    # Initialize GhostMind client (self-hosted, no API key)
    client = GhostMindClient(
        api_url="http://localhost:8000",  # Your self-hosted instance
        llm_adapter=llm,
        domain="medical"
    )
    
    # Commit trusted facts
    await client.commit_fact(
        text="Patient is allergic to penicillin",
        user_id="patient_001",
        energy=0.95
    )
    
    # Validate query (4-layer validation)
    result = await client.validate(
        text="Can I take amoxicillin?",
        user_id="patient_001"
    )
    
    print(f"Action: {result['action']}")  # "REJECT"
    print(f"Reason: {result['reason']}")  # "Drug allergy conflict"
    print(f"Explanation: {result['explanation']}")  # LLM-generated explanation

asyncio.run(main())

Configuration

GhostMind supports two configuration modes for defining custom domains:

Basic Mode: Python Code (Recommended)

Define domains directly in Python code for maximum flexibility:

from ghostmind_client import GhostMindClient, DomainConfig, EntityPattern, ConflictRule

# Define custom domain
hr_domain = DomainConfig(
    name="hr_policy",
    entity_patterns=[
        EntityPattern("employee_id", r'\bEMP\d{5}\b'),
        EntityPattern("vacation_days", r'(\d+)\s*vacation\s*days')
    ],
    conflict_rules=[
        ConflictRule(
            name="vacation_check",
            severity=ConflictSeverity.CRITICAL,
            checker=check_vacation_policy
        )
    ]
)

# Use with client
client = GhostMindClient(
    api_url="http://localhost:8000",
    llm_adapter=llm,
    domain_config=hr_domain  # Custom domain
)

Guides:

• Custom Configuration Guide - Full Python configuration
• Examples - Complete examples

Advanced Mode: Config Files (YAML/JSON)

For teams, version control, or dynamic deployment, use configuration files:

from ghostmind_client.config import DomainConfigLoader

# Load from YAML config file
loader = DomainConfigLoader()
hr_domain = loader.from_yaml("configs/hr_policy.yaml", checkers={
    "check_vacation_policy": check_vacation_policy,
    "check_expense_policy": check_expense_policy
})

# Use with client (same as Python mode)
client = GhostMindClient(domain_config=hr_domain, ...)

Config file example (hr_policy.yaml):

domain:
  name: hr_policy
  entities:
    - name: employee_id
      pattern: '\bEMP\d{5}\b'
  conflicts:
    - name: vacation_check
      severity: CRITICAL
      checker: check_vacation_policy

When to use config files:

• ✅ Version control for domain definitions
• ✅ Team collaboration (non-programmers can edit)
• ✅ Environment-specific configs (dev/staging/prod)
• ✅ Dynamic domain loading

Installation:

pip install pyyaml  # For YAML support

Guides:

• Configuration File Guide - Full YAML/JSON documentation
• Config Examples - Ready-to-use config files
• Config Example Code - How to load and use

API Reference

GhostMindClient

client = GhostMindClient(
    api_url="http://localhost:8000",  # GhostMind server URL
    llm_adapter=llm,                   # Your LLM adapter
    domain="medical",                  # Domain: medical, financial, general
    api_key=None,                      # Optional: API key for auth
    timeout=30                         # Request timeout (seconds)
)

Methods

validate()

Full 4-layer validation (most common)

result = await client.validate(
    text="Can I take amoxicillin?",  # User query
    user_id="patient_001",            # User identifier
    context=None                      # Optional context
)

# Returns:
{
    "action": "REJECT" | "ACCEPT" | "WARNING",
    "reason": "Drug allergy conflict",
    "intent": "REQUEST",
    "score": 0.15,
    "conflicting_facts": [...],
    "explanation": "⚠️ Safety Alert: ...",
    "total_latency_ms": 540
}

commit_fact()

Commit a trusted fact to long-term memory

result = await client.commit_fact(
    text="Patient is allergic to penicillin",
    user_id="patient_001",
    energy=0.95,  # Confidence (0.0-1.0)
    metadata={"source": "doctor_note", "date": "2024-01-15"}
)

# Returns:
{
    "session_id": "patient_001",
    "fact_id": "fact_abc123",
    "status": "committed"
}

extract()

Layer 2: Extract facts from text

result = await client.extract(
    text="Patient has severe penicillin allergy. Takes aspirin daily.",
    user_id="patient_001"
)

# Returns:
{
    "facts": [
        {
            "text": "Patient has severe penicillin allergy",
            "domain": "medical",
            "energy": 0.9,
            "metadata": {
                "entities": {"drug": "penicillin", "severity": "severe"}
            }
        },
        {
            "text": "Patient takes aspirin daily",
            "domain": "medical",
            "energy": 0.85,
            "metadata": {
                "entities": {"drug": "aspirin", "frequency": "daily"}
            }
        }
    ],
    "latency_ms": 15
}

rank()

Layer 3: Physics-based ranking

result = await client.rank(
    query_text="What allergies does the patient have?",
    user_id="patient_001",
    documents=[
        "Patient has severe penicillin allergy",
        "Patient has no known allergies",
        "Patient tolerates penicillin well"
    ],
    top_k=3
)

# Returns:
{
    "ranked_documents": [
        {
            "id": "doc_1",
            "text": "Patient has severe penicillin allergy",
            "score": 0.92,
            "rank": 1
        },
        # ... more documents
    ],
    "alpha": 0.7,  # Semantic weight
    "beta": 0.3,   # Energy weight
    "latency_ms": 45
}

get_commitments()

Retrieve all committed facts for a user

result = await client.get_commitments(user_id="patient_001")

# Returns:
{
    "session_id": "patient_001",
    "facts": [
        {
            "fact_id": "fact_abc123",
            "text": "Patient is allergic to penicillin",
            "domain": "medical",
            "energy": 0.95,
            "timestamp": "2024-01-15T10:30:00Z"
        },
        # ... more facts
    ],
    "count": 5
}

LLM Adapters

LMStudioAdapter

Best for: Desktop apps, testing, non-technical users

from ghostmind_client.llm import LMStudioAdapter

llm = LMStudioAdapter(
    model="local-model",
    base_url="http://localhost:1234/v1",
    temperature=0.1,
    max_tokens=500
)

Setup: See LM Studio Guide

OllamaAdapter

Best for: Servers, Docker, developers

from ghostmind_client.llm import OllamaAdapter

llm = OllamaAdapter(
    model="llama2",
    base_url="http://localhost:11434",
    temperature=0.1
)

Setup: See Ollama Guide

DummyLLM

Best for: Testing without LLM

from ghostmind_client.llm import DummyLLM

llm = DummyLLM()  # Simple rule-based logic

Custom Adapter

Bring your own LLM (OpenAI, Claude, etc.)

from ghostmind_client.llm import LLMAdapter, Intent

class MyCustomAdapter(LLMAdapter):
    async def parse_intent(self, text, context=None):
        # Your logic here
        return Intent.REQUEST
    
    async def generate_explanation(self, decision, text, context=None):
        # Your logic here
        return "Custom explanation"

Examples

Medical Safety System

# See: examples/example_medical.py
# - Patient allergy checking
# - Drug interaction detection
# - Dosage validation

Financial Compliance

# See: examples/example_financial.py
# - Transaction validation
# - Regulatory compliance
# - Conflict of interest detection

LM Studio Integration

# See: examples/example_lmstudio.py
# - Local inference with GUI
# - Privacy-first architecture
# - Easy model switching

Ollama Integration

# See: examples/example_ollama.py
# - CLI-based setup
# - Docker deployment
# - Production-ready

Performance

Latency Breakdown

Layer	Operation	Server	Client (LM Studio)	Total
1	Intent parsing	-	50-100ms	50-100ms
2	Fact extraction	10-20ms	-	10-20ms
3	Physics ranking	30-80ms	-	30-80ms
4	Explanation	-	200-500ms	200-500ms

End-to-end validation: ~300-700ms

Resource Usage

Server (NO LLM):

• RAM: 100-400MB
• CPU: <10% idle, 20-40% under load
• Storage: 50MB + data

Client (with LLM):

• RAM: 2-8GB (depends on model size)
• CPU/GPU: Varies by model
• Latency: 50-500ms per LLM call

Deployment

Development

# 1. Start server
cd KVM/server
uvicorn main:app --reload

# 2. Start LM Studio
# - Open LM Studio app
# - Load model (e.g., llama-2-7b)
# - Start local server (port 1234)

# 3. Run client
python examples/example_lmstudio.py

Production

Client Deployment:

# Option 1: Install from source
pip install -e client-sdk/

# Option 2: Package as wheel
cd client-sdk
python setup.py bdist_wheel
pip install dist/ghostmind_client-1.0.0-py3-none-any.whl

Server Deployment: See: Deployment Guide

Docker

Client (with Ollama):

FROM python:3.11-slim

# Install Ollama
RUN curl https://ollama.ai/install.sh | sh

# Install GhostMind client
COPY client-sdk /app/client-sdk
RUN pip install -e /app/client-sdk

# Pull model
RUN ollama pull llama2

CMD ["python", "/app/your_app.py"]

Note: LM Studio requires GUI, so use Ollama for Docker deployments.

Security

API Authentication

client = GhostMindClient(
    api_url="https://api.yourdomain.com",
    api_key="your_api_key_here",  # Server validates this
    llm_adapter=llm
)

Privacy Modes

Mode 1: Send full text (default)

# Client sends: "Can I take amoxicillin?"
# Server extracts facts, validates, returns decision
result = await client.validate(text=user_input, user_id="user123")

Mode 2: Extract locally, send only facts

# Client extracts: ["amoxicillin"]
# Client sends only extracted facts to server
# More private, but requires local extraction
# (Future feature - not implemented yet)

Data Retention

# Control how long server keeps sessions
# Set via server config: SESSION_TTL_SECONDS
# Default: 24 hours

Testing

Run Client Tests

cd client-sdk
pytest tests/

Run Integration Tests

# Make sure server is running first
python test_client_sdk.py

Manual Testing

# Quick health check
from ghostmind_client import GhostMindClient
from ghostmind_client.llm import DummyLLM

client = GhostMindClient(
    api_url="http://localhost:8000",
    llm_adapter=DummyLLM()
)

health = await client.health_check()
print(health)  # {"status": "healthy", "redis": "connected"}

Troubleshooting

"Cannot connect to server"

Fix:

# Check server is running
curl http://localhost:8000/health

# Start server if needed
cd KVM/server
uvicorn main:app --reload

"Cannot connect to LM Studio"

Fix:

1. Open LM Studio app
2. Go to "Local Server" tab
3. Click "Start Server"
4. Verify port is 1234

"Import error: cannot import name GhostMindClient"

Fix:

# Install client SDK
cd client-sdk
pip install -e .

# Or add to path
export PYTHONPATH=$PYTHONPATH:/path/to/client-sdk

Slow LLM responses (>2s)

Optimization:

1. Use smaller model (phi-2 instead of llama-2-13b)
2. Reduce max_tokens parameter
3. Enable GPU acceleration
4. Use quantized models (Q4, Q5)

Roadmap

• Ollama adapter
• LM Studio adapter
• OpenAI adapter
• Claude adapter
• Local extraction mode (privacy++)
• Streaming responses
• Batch validation
• WebSocket support

Contributing

We welcome contributions! Areas of interest:

• New LLM adapters (OpenAI, Claude, Gemini)
• Performance optimizations
• More examples
• Documentation improvements

License

See: LICENSE

Support

• Documentation: See docs/ folder
• Examples: See examples/ folder
• Issues: GitHub Issues (if open-sourced)
• Email: [e-mail] (if commercial)

---

Built with ❤️ for safe, physics-validated AI