Metadata-Version: 2.1
Name: khy-os
Version: 0.1.13
Summary: Khy OS — AI platform operating system with an extensible default app runtime
Author-email: khy-qqb <2578974124@qq.com>
License: MIT
Project-URL: Homepage, https://khyquant.top
Project-URL: Documentation, https://khyquant.top/docs
Project-URL: Repository, https://github.com/khyquant/khy-quant
Project-URL: Issues, https://github.com/khyquant/khy-quant/issues
Keywords: khy,ai-os,agent-os,platform-cli,extensible-runtime
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: JavaScript
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.25.0
Requires-Dist: cffi<3.0.0,>=1.15.0
Provides-Extra: data
Requires-Dist: akshare<2.0.0,>=1.12.0; extra == "data"
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "data"
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "data"
Provides-Extra: ml
Requires-Dist: khy-os[data]; extra == "ml"
Requires-Dist: scikit-learn==1.8.0; extra == "ml"
Requires-Dist: xgboost==3.2.0; extra == "ml"
Requires-Dist: lightgbm==4.6.0; extra == "ml"
Requires-Dist: joblib==1.5.3; extra == "ml"
Requires-Dist: scipy<2.0.0,>=1.10.0; extra == "ml"
Requires-Dist: ta<1.0.0,>=0.11.0; extra == "ml"
Requires-Dist: tqdm<5.0.0,>=4.65.0; extra == "ml"
Requires-Dist: pyyaml<7.0.0,>=6.0; extra == "ml"
Requires-Dist: loguru<1.0.0,>=0.7.0; extra == "ml"
Provides-Extra: doc
Requires-Dist: pdf2docx<1.0.0,>=0.5.6; extra == "doc"
Requires-Dist: pytesseract<1.0.0,>=0.3.10; extra == "doc"
Requires-Dist: Pillow<12.0.0,>=10.0.0; extra == "doc"
Provides-Extra: frontend
Requires-Dist: khy-quant-frontend<3.0.0,>=1.6.0; extra == "frontend"
Provides-Extra: backend
Requires-Dist: khy-quant-backend<3.0.0,>=1.6.0; extra == "backend"
Provides-Extra: full
Requires-Dist: khy-os[data]; extra == "full"
Requires-Dist: khy-os[ml]; extra == "full"
Requires-Dist: khy-os[doc]; extra == "full"
Provides-Extra: all
Requires-Dist: khy-os[full]; extra == "all"
Provides-Extra: local-llm
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"

# Khy OS

Khy OS is an AI platform CLI and runtime. The default built-in app is `khyquant`.

## Positioning

- `khy` is the primary Khy OS command (platform shell + app runtime).
- `khyquant` is the default upper-layer app/plugin compatibility command.
- AI lite mode is explicit: use `khy ai ...` (or `khy --lite ...`).
- In the KHY-OS vision, AI is a local super-admin, a remote SSH environment operator, and a mobile-safe context translator (redacted, approval-gated, mobile-first output).

## Release Notes (0.1.3)

This release focuses on vision/multimodal adapter compatibility and packaging consistency.

### Highlights

- Unified image normalization for gateway adapters:
  - added shared image compatibility layer for base64/data-url/url payloads
  - mapped unified image input to adapter-specific formats (Codex/Claude/Ollama/OpenAI-compatible IDE adapters)
- Removed forced image routing to Claude by default:
  - image requests now keep the selected adapter first
  - gateway fallback remains enabled when a channel actually fails
- Improved local/IDE multimodal behavior:
  - Codex direct mode accepts normalized images
  - Ollama adapter accepts normalized image payloads for multimodal models
  - Trae/Windsurf adapters accept OpenAI-compatible vision message blocks
- Packaging/release consistency:
  - synchronized package version metadata for `khy-os==0.1.3`
  - fixed release path to avoid mixed/legacy install metadata

### Upgrade

```bash
python3 -m pip install -U khy-os==0.1.3
khy --version
```

---

## Release Notes (0.1.2)

This release focuses on production stability, multi-adapter robustness, and clearer operator experience.

### Highlights

- Improved AI request stability for long-running tasks:
  - task-scale-aware retry/timeout strategy
  - transient error recovery across gateway and tool loop layers
  - safer adapter failover behavior when preferred channels are unstable
- Better context-window safety:
  - dynamic context budget handling
  - stronger compaction path for oversized histories
- Better terminal UX:
  - improved status signaling and de-duplication
  - stronger recovery for interactive input states
- Packaging/version sync:
  - synchronized version bump across Python + Node entry metadata
- release artifacts generated for `khy-os==0.1.2`

### Upgrade

```bash
python3 -m pip install -U khy-os==0.1.2
khy --version
```

### Compatibility

- Python: `>=3.8`
- Node.js: `>=18`
- OS: Linux / macOS / Windows

## Directory Structure

```text
Khy-OS/
├─ khy_quant/                     # Python launcher package (PyPI entrypoint)
│  ├─ cli.py                      # Main Python CLI bridge
│  ├─ _bootstrap.py               # Runtime bootstrap checks/fixes
│  └─ bundled/                    # Bundled runtime assets for pip distribution
│
├─ backend/                       # Node.js core runtime
│  ├─ bin/khyquant.js             # Node CLI entrypoint
│  ├─ server.js                   # API server entrypoint
│  ├─ src/
│  │  ├─ cli/                     # REPL/router/handlers
│  │  ├─ routes/                  # HTTP routes
│  │  ├─ services/                # Gateway, adapters, tools, orchestration
│  │  ├─ tools/                   # Tool implementations
│  │  ├─ models/                  # Data models
│  │  └─ middleware/              # Auth/rate-limit/error middleware
│  └─ tests/                      # Backend tests
│
├─ frontend/                      # Vue frontend
│  ├─ src/
│  │  ├─ components/              # UI components
│  │  ├─ views/                   # Page views
│  │  ├─ services/                # Frontend service layer
│  │  └─ stores/                  # State stores
│  └─ public/                     # Static assets
│
├─ packages/shared/               # Shared JS modules (backend/frontend)
├─ docs/                          # Architecture, guides, verification docs
├─ scripts/                       # Build/install/release scripts
├─ pyproject.toml                 # Python package metadata
└─ backend/package.json           # Node backend metadata
```

## Quick Start

```bash
python3 -m pip install -U khy-os
khy --help
khy doctor
khy app list
```

Development install:

```bash
python3 -m pip install -e .
```

## Install Modes

| Command | Contents | Size |
|---|---|---|
| `pip install khy-os` | Core CLI + Node backend | ~5 MB |
| `pip install khy-os[data]` | + pandas / numpy / akshare | +~50 MB |
| `pip install khy-os[ml]` | + sklearn / xgboost / lightgbm | +~200 MB |
| `pip install khy-os[doc]` | + pdf2docx / pytesseract / Pillow | +~30 MB |
| `pip install khy-os[full]` | data + ml + doc | ~260 MB |

### Local LLM Inference (not included in pip)

Local inference binaries (ollama-runner, llama.cpp) are **not bundled** in the pip
package — they are platform-specific and too large (~130 MB). Install separately:

| Component | Install | Notes |
|---|---|---|
| **Ollama** (recommended) | `curl -fsSL https://ollama.com/install.sh \| sh` (Linux/macOS) or [Download](https://ollama.com/download) (Windows) | Auto-manages models, easiest setup |
| **llama.cpp** | Download from [GitHub Releases](https://github.com/ggml-org/llama.cpp/releases) | Advanced users, manual model management |

After installing, verify with:

```bash
khy doctor          # checks all available inference backends
khy ai run qwen3.5:4b "hello"   # test local inference
```

If no local LLM is installed, the AI gateway falls back to remote API providers
(Gemini, Groq, OpenRouter, etc.) — core functionality is not affected.

## Core Commands

```bash
khy app list
khy gateway status
khy linux status
khy server start
```

## Explicit AI Lite Mode

```bash
khy ai "summarize this project status"
khy ai -p "only output JSON"
khy ai run qwen3.5:4b "hello"

# compatibility alias (kept for older scripts)
khy run qwen3.5:4b "hello"
```

## OS Build Entry

```bash
bash scripts/build-khy-os.sh
```

Windows (Docker Desktop + PowerShell):

```powershell
khy iso build --output dist/khy-os.iso
# equivalent source script:
# powershell -ExecutionPolicy Bypass -File scripts/alpine/build-iso-windows.ps1
```

Component mode:

```bash
bash scripts/build-khy-os.sh --component core --component vmware-plan
bash scripts/build-khy-os.sh --component moonbit --strict
```

## WASM App Runtime

```bash
khy app register math --runtime wasm --wasm /abs/path/math.wasm --abi numeric-v1 --export add
khy app run math add 1 2

khy app register echo --runtime wasm --wasm /abs/path/echo.wasm --abi string-v2 --export run
khy app exports echo
khy app run echo hello khy os

khy app register score --runtime wasm --wasm /abs/path/score.wasm --abi json-v2 --export run
khy app run score --json '{"symbol":"AAPL","price":192.3,"rsi":63.2}'

# M1 IPC simulation (loopback netd/fsd/wmd)
khy app register weather --runtime wasm --wasm /abs/path/weather.wasm --abi json-v2 --export run --caps ipc,net
khy app ipc weather net http_get --json '{"city":"shanghai"}'
```

## Required Environment

- Python >= 3.8
- Node.js >= 18
- Linux/macOS/Windows

## Docker Compose One-Command Startup

Default startup (SQLite mode, no extra manual config required):

```bash
docker compose up -d --build
docker compose ps
```

Verification endpoints:

- Frontend: `http://localhost:18080`
- Backend health: `http://localhost:13000/health`
- AI frontend: `http://localhost:18090`

Optional environment overrides:

```bash
cp .env.example .env
# edit .env if you want custom ports or secrets
docker compose up -d --build
```

Optional PostgreSQL profile:

```bash
DB_TYPE=postgres docker compose --profile postgres up -d --build
```

## Pip Distribution Boundary

- Prebuilt ISO/model artifacts and local LLM binaries are intentionally excluded from pip packages.
- You can build ISO locally after installation (`khy iso build ...`).
- You can download and register models on demand:

```bash
khy models pull qwen3.5:4b
khy models list
khy gateway model
```

See:
- `docs/architecture/CORE_ARCHITECTURE.md`
- `docs/guides/ENV_REQUIREMENTS.md`
