Metadata-Version: 2.4
Name: kstudiochat
Version: 1.1.0
Summary: K-CHAT — Universal Chatbot Engine. Anti-hallucination by construction.
Author: K-CHAT Contributors
License: MIT
Keywords: chatbot,rag,anti-hallucination,nlp,ai,framework,universal
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: deepseek
Requires-Dist: openai>=1.0.0; extra == "deepseek"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# K-CHAT — Universal Chatbot Engine

**Zero-hallucination chatbot engine. Folder-based. No ML expertise needed.**

```bash
pip install kstudiochat
kstudiochat init ./bot --template restaurant
kstudiochat chat --data ./bot
```

Three commands. Working bot. No API key required (SimulatedLLM built-in).

---

## Quick Start

```bash
# Install
pip install kstudiochat

# Create a bot from a pre-built template
kstudiochat init ./bot --template government

# Chat (uses SimulatedLLM — offline, no API key)
kstudiochat chat --data ./bot

# Or use a real LLM
pip install kstudiochat[openai]
# Edit bot/config.json → llm.provider: "openai" | "deepseek" | "mimo"
```

### Templates

| Template | Description |
|----------|-------------|
| `government` | FAQ for passports, permits, taxes |
| `restaurant` | Menu, hours, reservations |
| `healthcare` | General health info, clinic FAQ |

---

## How It Works

Drop a folder. Get a chatbot. No code.

```
my-bot/
├── config.json       # Bot identity, LLM provider
├── knowledge/        # Documents the bot answers from
│   ├── faq.md
│   └── pricing.md
├── SOUL.md           # Personality (optional)
├── intents.json      # Keywords (optional)
└── refusal.json      # Fallback messages (optional)
```

### Pipeline

```
User → Sanitize → Ethics → Intent → Feed ALL data → LLM → Verify → Response
```

Three-gate prompt:
- **Gate 1** — Greeting/thanks/farewell → LLM without data (natural)
- **Gate 2** — Questions → LLM with all knowledge chunks
- **Gate 3** — Out of scope → Polite redirect

### Anti-Hallucination

- Grounded prompt: LLM answers only from provided data
- Verification: entity consistency + overlap check
- Refusal detection: catches "I don't know" responses
- Ethical guard: blocks harmful content

---

## LLM Providers

| Provider | Model | Config |
|----------|-------|--------|
| **Simulated** (built-in, offline) | `simulated` | Default — no setup |
| **OpenAI** | `gpt-4o-mini` | Set `OPENAI_API_KEY` |
| **DeepSeek** | `deepseek-v4-flash` | Set `DEEPSEEK_API_KEY` |
| **Xiaomi MiMo** | `mimo-v2-flash` | Set `MIMO_API_KEY` |

```json
"llm": {"provider": "mimo", "model": "mimo-v2-flash", "temperature": 0.3}
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `kstudiochat init <path>` | Create a new pack |
| `kstudiochat init <path> --template <name>` | Create from template |
| `kstudiochat templates` | List templates |
| `kstudiochat chat --data <path>` | Interactive chat |
| `kstudiochat serve --data <path>` | REST API server |
| `kstudiochat validate --data <path>` | Validate pack |
| `kstudiochat info --data <path>` | Show config |

---

## Multi-Tenant API (for clients)

K-CHAT can run as a multi-tenant API — clients upload their data and get a chatbot endpoint.

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/packs` | Upload zip → get API key |
| `POST` | `/api/chat` | Chat with bot (`Authorization: Bearer kc_xxx`) |
| `DELETE` | `/api/packs/:id` | Delete pack |
| `GET` | `/api/widget.js?key=xxx` | Widget embed snippet |

### Client embed (shared hosting)

```html
<div id="kchat-widget"></div>
<script src="https://your-api.url/api/widget.js?key=kc_xxx"></script>
```

### Direct API usage

```bash
curl -X POST https://your-api.url/api/chat \
  -H "Authorization: Bearer kc_xxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your hours?"}'
```

---

## Extensions

Config-driven, enabled via `config.json`:

```json
"extensions": {
  "conversational_memory": {"enabled": true},
  "predictive": {"enabled": true},
  "multimodal": {"enabled": true}
}
```

| Extension | What it does |
|-----------|-------------|
| `conversational_memory` | Tracks user preferences, mood |
| `multimodal` | Enhances emotion detection |
| `predictive` | Flags risky interactions |
| `live` | Injects real-time data |
| `adaptive` | Tracks strategy effectiveness |
| `rlhf` | Collects feedback |
| `voice` | STT → chat → TTS pipeline |

---

## Why K-CHAT?

| Instead of... | K-CHAT gives you |
|--------------|------------------|
| LangChain | Folder-based data contract, zero code |
| Building from scratch | Anti-hallucination out of the box |
| SaaS chatbots ($30+/mo) | One-time deploy, free to run |
| ML pipelines | Deterministic, auditable verification |

---

## License

MIT
