Metadata-Version: 2.4
Name: kstudiochat
Version: 1.0.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 by construction.**  
Drop a folder of documents. Get a chatbot. No ML expertise needed.

```bash
pip install kchat
kchat init ./helpdesk --template government
kchat chat --data ./helpdesk
```

**Three commands. Working bot. No API key required.**

---

## Quick Start

```bash
# Install
pip install kchat

# Create a bot from a pre-built template
kchat init ./my-bot --template restaurant

# Chat with it (uses SimulatedLLM — works offline, no API key)
kchat chat --data ./my-bot

# Or use OpenAI/DeepSeek
pip install kchat[openai]
# Edit my-bot/config.json → change llm.provider to "openai" or "deepseek"
```

### Available templates

```bash
kchat templates
```

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

---

## How It Works

K-CHAT uses an **Industry Pack** — a folder of data files. No code changes needed to onboard a new domain.

```
my-industry-pack/
├── config.json       # Bot identity, LLM choice, retrieval settings
├── intents.json      # Intent taxonomy (optional)
├── refusal.json      # Fallback responses + escalation contact
├── knowledge/        # Documents the bot answers from
│   ├── overview.md
│   └── faq.md
├── context/          # Style guides, policies (optional)
├── SOUL.md           # Personality definition (optional)
├── skills/           # Custom Python workflows (optional)
└── tools/            # Custom API tools (optional)
```

The pipeline:

```
User Input → Sanitize → Ethics Check → Intent Classify → Emotion Detect
→ Cultural Adapt → Retrieve Knowledge → LLM (grounded prompt)
→ Anti-Hallucination Verify → Tone Apply → Response
```

### Anti-Hallucination

K-CHAT never asks the LLM to recall facts. It:
1. Injects only retrieved context into the prompt
2. Verifies every response against the source documents
3. Falls back to extractive answers if verification fails

Three verification strategies: **entity consistency**, **citation coverage**, **text overlap**.

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `kchat init <path>` | Create a new industry pack |
| `kchat init <path> --template <name>` | Create from pre-built template |
| `kchat templates` | List available templates |
| `kchat chat --data <path>` | Interactive chat in terminal |
| `kchat serve --data <path>` | REST API server (stdlib HTTP) |
| `kchat validate --data <path>` | Validate pack structure |
| `kchat curate --data <path>` | Audit knowledge quality |
| `kchat info --data <path>` | Show resolved config |
| `kchat audit --data <path>` | Full self-audit |

### Chat REPL

```
(My Bot) You > /help
  /quit   - Exit
  /clear  - Clear screen
  /multiline - Enter multiline mode (end line with """)
  /help   - Show this help

(My Bot) You > What are your hours?
Bot: We are open Monday to Saturday: Lunch 11-2:30, Dinner 5-10.
  sources: faq.md | confidence: High (0.93) | intent: info_lookup
```

### REST API

```bash
kchat serve --data ./my-bot --port 8000
curl -X POST http://localhost:8000/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "What are your hours?"}'
```

Endpoints: `GET /health`, `POST /chat`, `WS /ws`, `GET /info`

Auth: set `KCHAT_API_KEY` env var. Rate limit: set `KCHAT_RATE_LIMIT` (req/min).

---

## Extensions

Enable via `config.json`:

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

| Extension | What it does |
|-----------|-------------|
| `live` | Injects real-time data into context (prices, queues, sensors) |
| `conversational_memory` | Tracks user preferences, mood, relationship stage |
| `multiagent` | Routes queries to specialist agents |
| `multimodal` | Enhances emotion detection (text + optional voice/visual) |
| `adaptive` | Tracks strategy effectiveness, recommends adjustments |
| `predictive` | Assesses risk based on mood patterns and conversation signals |
| `rlhf` | Collects feedback and computes reward signals |
| `voice` | STT → Bot.chat() → TTS pipeline |

Import directly: `from engine.extensions.voice import VoiceManager`

---

## Configuration

Minimal `config.json`:

```json
{
  "name": "My Bot",
  "persona": "Helpful, accurate, and concise.",
  "llm": {"provider": "simulated"}
}
```

Available LLM providers: `simulated` (default, offline), `openai`, `deepseek`.

Full config reference: `kchat info --data ./my-bot`

---

## Deployment

### Railway

```bash
# Deploy from GitHub
# Set KCHAT_DATA=./my-bot
# Set PORT=8000
```

### VPS / Docker

```bash
# Install, create pack, run server
pip install kchat
kchat init ./my-bot --template government
kchat serve --data ./my-bot --host 0.0.0.0 --port 8000
```

### Vercel (serverless)

See `clients/nail-art/` for a working Vercel deployment example.

---

## Why K-CHAT?

| Instead of... | K-CHAT gives you... |
|--------------|-------------------|
| LangChain (framework) | A turnkey engine with a data contract |
| Building from scratch | Anti-hallucination out of the box |
| Paying per chatbot | One engine, infinite domains |
| Complex ML pipelines | Deterministic, auditable verification |

---

## License

MIT
