Metadata-Version: 2.4
Name: ixv-core
Version: 0.4.1
Summary: Local LLM server with OpenAI-compatible API
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: llama-cpp-python>=0.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: slowapi>=0.1.9

# IXV-Core v0.4.0

ローカルLLMを OpenAI API互換で提供するサーバー。

## 概要

IXV-Core は、llama.cpp (llama-cpp-python) を使用して、
ローカル環境でLLMを動作させ、OpenAI API互換のエンドポイントを提供します。

Cursor や VS Code などの AI エディタから、
クラウドLLMの代わりにローカルLLMを使用できます。

### v0.4.0 の新機能

- **スキルシステム**: LLMと連携して様々な操作を実行する拡張機能
  - ファイル操作、コード実行、Git操作、RAG、Web検索
  - コード分析、コーディング規約チェック、設計整合性チェック（オプション）
  - `/ixv/skills/*` エンドポイント追加

### v0.3.0 の機能

- **GPU対応**: Metal/GPUアクセラレーションをサポート（10-50倍の推論速度向上）
- **同時実行数制限**: 推論リクエストの並行処理を制限（リソース保護）
- **会話メモリの永続化**: サーバー再起動後も会話履歴を保持可能
- **モデルメタデータ取得**: `/ixv/model/info` エンドポイント追加
- **プロンプトテンプレート統合**: Chat Completionsに `prompt_type` パラメータ追加

## クイックスタート

### 1. インストール

```bash
# クローン
git clone https://github.com/yourname/ixv-core.git
cd ixv-core

# 依存パッケージのインストール
pip install -e .
```

### 2. モデルの準備

GGUF形式のモデルファイルをダウンロードします。

```bash
# 単一ファイルのモデル
./scripts/download_model.sh <repo_id> <filename>

# 分割モデル（フォルダ指定）
./scripts/download_model.sh <repo_id> --include "<pattern>"

# 例: gpt-oss-120b F16版（約65GB、単一ファイル）
./scripts/download_model.sh unsloth/gpt-oss-120b-GGUF gpt-oss-120b-F16.gguf

# 例: gpt-oss-120b Q4_K_M版（約62GB、分割モデル）
./scripts/download_model.sh unsloth/gpt-oss-120b-GGUF --include "Q4_K_M/*"
```

モデルは `models/` ディレクトリに保存されます。

### 3. 起動

```bash
# 単一ファイルモデル
export IXV_MODEL_PATH=models/gpt-oss-120b-F16.gguf
./scripts/start_mac.sh

# 分割モデル（最初のファイルを指定、残りは自動で読み込み）
export IXV_MODEL_PATH=models/Q4_K_M/gpt-oss-120b-Q4_K_M-00001-of-00002.gguf
./scripts/start_mac.sh
```

### 4. 動作確認

```bash
curl http://localhost:8000/ixv/health

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ixv-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## 設定

環境変数で設定を変更できます：

| 変数名 | デフォルト | 説明 |
|--------|-----------|------|
| `IXV_MODEL_PATH` | `models/ixv-model.gguf` | モデルファイルパス |
| `IXV_PORT` | `8000` | ポート番号 |
| `IXV_N_CTX` | `4096` | コンテキスト長 |
| `IXV_N_THREADS` | `8` | スレッド数 |
| `IXV_N_GPU_LAYERS` | `-1` | GPUレイヤー数（-1=全レイヤーGPU, 0=CPUのみ） |
| `IXV_DEBUG` | `false` | デバッグモード |
| `IXV_RATE_LIMIT_ENABLED` | `true` | レート制限の有効化 |
| `IXV_RATE_LIMIT_REQUESTS` | `10` | レート制限: リクエスト数 |
| `IXV_RATE_LIMIT_PERIOD` | `minute` | レート制限: 期間 (second/minute/hour/day) |
| `IXV_MAX_CONCURRENT_INFERENCES` | `2` | 同時実行可能な推論数 |
| `IXV_MEMORY_PERSISTENCE` | `false` | 会話メモリの永続化 |
| `IXV_SKILLS_ENABLED` | `true` | スキルシステムの有効化 |

詳細は [仕様書](docs/spec.md) を参照してください。

## API

### OpenAI互換

- `POST /v1/chat/completions` - Chat Completions
- `GET /v1/models` - モデル一覧

### IXV独自

- `GET /ixv/health` - ヘルスチェック
- `GET /ixv/logs` - 推論ログ
- `GET /ixv/memory` - 会話メモリ
- `POST /ixv/memory/clear` - メモリクリア
- `GET /ixv/config` - 設定確認
- `GET /ixv/model/info` - モデルメタデータ取得
- `GET /ixv/prompts/types` - プロンプトテンプレート一覧

### スキルAPI (v0.4.0)

- `GET /ixv/skills` - スキル一覧
- `GET /ixv/skills/{skill_name}` - スキル詳細
- `POST /ixv/skills/execute` - スキル実行
- `POST /ixv/skills/{skill_name}/enable` - スキル有効化
- `POST /ixv/skills/{skill_name}/disable` - スキル無効化

## 既知の問題

- [会話を続けるとコンテキストウィンドウ超過エラーが発生する](https://github.com/elvezjp/ixv/issues/5) - 会話メモリの蓄積により4096トークンの上限を超過する場合があります。回避策: `/ixv/memory/clear` でメモリをクリア

## ドキュメント

- [仕様書](docs/spec.md) - 詳細な仕様
- [テスト手順](docs/testing.md) - 接続テストガイド
- [スキルテスト](docs/testing-skills.md) - スキル動作確認テスト
- http://localhost:8000/docs - Swagger UI（起動後）

## ライセンス

MIT
