local-automata 0.2.5

ローカルLLM（mlx / llama.cpp / OpenAI互換）で動く、ツール・プロファイル対応の汎用エージェントのコア

local-automata

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

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

クイックスタート

uv を使う。3ステップで動く。

# 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）。

使い方（ブラウザ GUI）

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

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 引数や環境変数では指定しない。

# 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 を参照。

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

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

mcp_dir = "AIOS"

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

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

サンプル

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

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

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

構成とテスト

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

uv run pytest

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