Metadata-Version: 2.4
Name: ghostmind-client
Version: 1.1.0
Summary: Ultra-lightweight client SDK for GhostBox.in - customer-controlled compliance validation
Home-page: https://github.com/GhostBoxAI/GhostMind-SDK
Author: GhostMind Team
Author-email: GhostBox Team <aniketvaidya@ghostbox.in>
Maintainer-email: GhostBox Team <aniketvaidya@ghostbox.in>
License: MIT
Project-URL: Homepage, https://github.com/GhostBoxAI/GhostMind-SDK
Project-URL: Documentation, https://docs.ghostmind.ai
Project-URL: Repository, https://github.com/GhostBoxAI/GhostMind-SDK
Project-URL: Issues, https://github.com/GhostBoxAI/GhostMind-SDK/issues
Project-URL: Changelog, https://github.com/GhostBoxAI/GhostMind-SDK/blob/main/CHANGELOG.md
Keywords: compliance,validation,llm,enterprise,gdpr,sox,hipaa,customer-controlled,domain-specific,conflict-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: xml
Requires-Dist: xmltodict>=0.13.0; extra == "xml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.0.270; extra == "dev"
Provides-Extra: all
Requires-Dist: pyyaml>=6.0; extra == "all"
Requires-Dist: xmltodict>=0.13.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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](https://ghostbox.in) 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](../SAAS/INSTANCE_ARCHITECTURE.md) 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](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](docs/SELF_HOSTING.md)

### 2. Install

```bash
# 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](docs/LM_STUDIO_GUIDE.md)

**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+):**

```python
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:**

```python
# Connect with email (first time)
client = await GhostMindClient.connect(
    llm=OllamaAdapter(model="llama2"),
    email="you@example.com",
    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:**

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

**Environment Variables:**

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

# Or use .env file
```

```python
# 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):**

```python
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):**

```python
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:

```python
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](docs/CUSTOM_CONFIGURATION_GUIDE.md) - Full Python configuration
- [Examples](examples/example_custom_domain.py) - Complete examples

### Advanced Mode: Config Files (YAML/JSON)

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

```python
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`):**
```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:**
```bash
pip install pyyaml  # For YAML support
```

**Guides:**
- [Configuration File Guide](docs/CONFIGURATION_FILE_GUIDE.md) - Full YAML/JSON documentation
- [Config Examples](examples/configs/) - Ready-to-use config files
- [Config Example Code](examples/example_config_file.py) - How to load and use

## API Reference

### GhostMindClient

```python
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)**

```python
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**

```python
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**

```python
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**

```python
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**

```python
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

```python
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](docs/LM_STUDIO_GUIDE.md)

### OllamaAdapter

**Best for:** Servers, Docker, developers

```python
from ghostmind_client.llm import OllamaAdapter

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

**Setup:** See [Ollama Guide](docs/OLLAMA_GUIDE.md)

### DummyLLM

**Best for:** Testing without LLM

```python
from ghostmind_client.llm import DummyLLM

llm = DummyLLM()  # Simple rule-based logic
```

### Custom Adapter

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

```python
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

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

### Financial Compliance

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

### LM Studio Integration

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

### Ollama Integration

```python
# 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

```bash
# 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:**
```bash
# 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](../KVM/DEPLOYMENT.md)

### Docker

**Client (with Ollama):**
```dockerfile
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

```python
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)**
```python
# 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**
```python
# Client extracts: ["amoxicillin"]
# Client sends only extracted facts to server
# More private, but requires local extraction
# (Future feature - not implemented yet)
```

### Data Retention

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

## Testing

### Run Client Tests

```bash
cd client-sdk
pytest tests/
```

### Run Integration Tests

```bash
# Make sure server is running first
python test_client_sdk.py
```

### Manual Testing

```python
# 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:**
```bash
# 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:**
```bash
# 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

- [x] Ollama adapter
- [x] 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](../LICENSE)

## Support

- **Documentation**: See `docs/` folder
- **Examples**: See `examples/` folder
- **Issues**: GitHub Issues (if open-sourced)
- **Email**: support@ghostmind.ai (if commercial)

---

**Built with ❤️ for safe, physics-validated AI**
