Metadata-Version: 2.4
Name: local-automata
Version: 0.2.9
Summary: ローカルLLM（mlx / llama.cpp / OpenAI互換）で動く、ツール・プロファイル対応の汎用エージェントのコア
Author: ToPo-ToPo-ToPo
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/ToPo-ToPo-ToPo/local-automata
Keywords: llm,agent,coding-agent,local-llm,mlx,llama.cpp,openai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Requires-Dist: mcp>=1.27
Requires-Dist: pypdf>=4.0
Requires-Dist: pymupdf>=1.24
Requires-Dist: pyyaml>=6.0
Requires-Dist: mlx-lm>=0.31.3; sys_platform == "darwin" and platform_machine == "arm64"
Requires-Dist: mlx-vlm>=0.5.0; sys_platform == "darwin" and platform_machine == "arm64"
Requires-Dist: mlx-whisper>=0.4; sys_platform == "darwin" and platform_machine == "arm64"
Requires-Dist: twine>=6.2.0
Provides-Extra: science
Requires-Dist: matplotlib>=3.10; extra == "science"
Requires-Dist: numpy>=2.0; extra == "science"
Requires-Dist: pandas>=2.2; extra == "science"
Requires-Dist: scikit-learn>=1.5; extra == "science"
Requires-Dist: scipy>=1.13; extra == "science"
Requires-Dist: sympy>=1.13; extra == "science"
Dynamic: license-file

# local-automata

ローカルLLM（mlx / llama.cpp）で動く、最小の汎用コーディングエージェント。
LLM とツール（ファイル読み書き・編集・検索・シェル実行）を組み合わせた agent loop が土台で、
設定（`agent.toml` ＋ 指示 `AGENTS.md`）だけでコーダー以外のエージェント
（キャラクターチャット等）にも転用できる。

> **この README は最短で動かすための要点だけです。使い方・設定の詳細はすべて [`docs/`](docs/) にまとめています**（末尾の[ドキュメント](#ドキュメント)一覧から該当ページへ）。

## クイックスタート

[uv](https://docs.astral.sh/uv/) を使う。3ステップで動く。

```sh
# 1. 環境構築（OS を自動判定。Apple Silicon では mlx も入る）
uv sync

# 2. ローカルLLMサーバーを起動（別ターミナルで）
uv run local-automata-server

# 3. ブラウザのチャット GUI を起動（http://127.0.0.1:8765）
uv run local-automata-web
```

> `agent.toml` に `auto_start = true` を書けば**ステップ2は不要**（サーバー未起動時に自動で立ち上げ、終了時に止める）。`examples/` の各サンプルはこの方式なので、ディレクトリで `uv run local-automata-web` を実行するだけで動く。

モデル・接続先・ツールなどの挙動はすべて **`agent.toml`（無ければ既定値）** で決まる。
ターミナルで対話したい場合は `local-automata` も使える（→ [docs/cli.md](docs/cli.md)）。

## 使い方（ブラウザ GUI）

追加依存なし（標準ライブラリのみ）の簡易チャット画面。

```sh
uv run local-automata-web                 # http://127.0.0.1:8765 を開く
uv run local-automata-web --port 9000 --no-browser
```

- プロンプトを入力するたびに、エージェントがツールを使ってタスクを進める。応答は SSE でストリーミング表示。
- **生成した画像・動画は作られたその場でインライン表示**する。
- ツール呼び出し・生成コードは**折り畳みブロック**で表示（クリックで開閉）。数式は KaTeX で表示。
- 入力欄の **🖼 ボタン/貼り付けで画像添付**、**🎤 ボタンで音声入力**（`[voice]` 有効時のみ）。
- 「＋ New chat」でセッションを切替。生成物は `workspace/<日時>_<タイトル>/` に保存。
- 待受ポートは `agent.toml` の `web_port` でも指定できる（`--port` が優先）。
- 変更が反映されないときは **Cmd+Shift+R（ハードリロード）**。

## 設定（agent.toml）

モデル・パラメータ・運用設定はすべて `agent.toml`（＋既定値）で決まる。CLI 引数や環境変数では指定しない。

```toml
# agent.toml（最小例。すべて省略可・省略時は既定値）
model = "mlx-community/Qwen3.6-27B-4bit"
base_url = "http://localhost:8080/v1"
auto_start = true                # サーバーを自動で立ち上げる
tools = ["read_file", "edit_file", "run_command"]
```

全キーの一覧・プロファイル・複数エージェントのポート設計は **[docs/configuration.md](docs/configuration.md)** を参照。

## 外部ツール（MCP）をすぐ使う

`agent.toml` に1行 `mcp_dir = "AIOS"` を書き、そのフォルダに MCP サーバーのコードを置くだけ。
エージェントが**最初から全ツールを認識**し、**呼んだ瞬間に裏で自動起動**する（事前の手動起動は不要）。

```toml
mcp_dir = "AIOS"
```

```
AIOS/
├── calc.py            # → サーバー "calc"
└── weather/server.py  # → サーバー "weather"
```

名指し宣言（`[mcp.servers.*]`）・起動モード（`mcp_mode`）・結合度の使い分けは
**[docs/tools-and-mcp.md](docs/tools-and-mcp.md)** を参照。

## サンプル

`examples/` に用途別のエージェント一式がある。サーバーを起動した上で、各ディレクトリで実行する。

| ディレクトリ | 内容 |
| --- | --- |
| `examples/character/` | 会話のみ（ツールなし）＋長期メモリの「ルナ」 |
| `examples/coder/` | 汎用コーディングエージェント（既定 Qwen3.6 + MTP）。作成・修正 → 実行 → 検証 |
| `examples/optimizer/` | 作成 → 実行 → 評価 → やり直しを固定ワークフローで反復 |
| `examples/ml/` | CSV から前処理 → 学習 → 評価 → 保存 |

```sh
cd examples/coder
uv run local-automata-web    # ブラウザ GUI（agent.toml を自動読込。生成物は ./workspace/）
uv run local-automata        # ターミナルで対話したい場合（→ docs/cli.md）
uv run python run_coder.py   # ライブラリとして埋め込む例
```

詳細は各ディレクトリの `README.md` を参照。

## ドキュメント

使い方・設定の詳細はこちら（MCP サーバーの探索方法 `mcp_dir` / `mcp_mode` などは tools-and-mcp.md を参照）:

- [docs/cli.md](docs/cli.md) — ターミナルで使う（`local-automata`）、添付、複数エージェントの同時実行
- [docs/configuration.md](docs/configuration.md) — `agent.toml` 全リファレンス、プロファイル、複数エージェント、機能トグル（tool_mode / verbose / thinking / planning / memory）
- [docs/tools-and-mcp.md](docs/tools-and-mcp.md) — 組み込みツールと安全性、MCP サーバーの探索・起動方法（`mcp_dir` / AIOS フォルダ方式 / `mcp_mode`）
- [docs/llm-server.md](docs/llm-server.md) — ローカルLLMサーバー、投機的デコード（MTP）、画像・動画（vision）、音声（voice）、接続
- [docs/workflows.md](docs/workflows.md) — 固定ワークフロー（YAML / Markdown）の書き方
- [docs/library.md](docs/library.md) — ライブラリとして組み込む、入力アダプタ
- [docs/troubleshooting.md](docs/troubleshooting.md) — よくある症状と対処
- [SPEC.md](https://github.com/ToPo-ToPo-ToPo/local-automata/blob/main/SPEC.md) — 挙動の詳細仕様

## 構成とテスト

Python パッケージ本体は `backend/local_automata/`、テストは `tests/`、開発用スクリプトは `scripts/`。

```sh
uv run pytest

# MCP 連携（cwd / タイムアウト / 進捗 / キャンセル）を実サーバー込みで一括確認
bash scripts/verify_mcp.sh
```
