columbina 0.1.0__tar.gz

columbina-0.1.0/.gitattributes

@@ -0,0 +1,8 @@
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+*.png binary
+*.gif binary
+*.jpg binary
+*.pdf binary

columbina-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    # A test that fails and then never ends would hold a runner for six hours.
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Images for the tests of the container sandbox and of the benchmark
+        if: runner.os == 'Linux'
+        run: |
+          docker pull -q debian:bookworm-slim
+          docker pull -q busybox
+          docker pull -q python:3.12-slim
+
+      - name: Test
+        run: uv run python -m coverage run -m pytest --junitxml=junit.xml
+        env:
+          # On Linux the tests with a real Docker engine have to run. A runner without an
+          # engine or without the images fails; it does not pass them over.
+          COLUMBINA_REQUIRE_DOCKER: ${{ runner.os == 'Linux' && '1' || '' }}
+
+      - name: Coverage
+        run: uv run python -m coverage report
+
+      # The log of a run can be read only when one is signed in. Its summary and its
+      # annotations can be seen by anyone, and the annotations read through the API.
+      # The script needs nothing but Python, so it runs even where the install failed.
+      - name: What failed
+        if: failure()
+        shell: bash
+        run: |
+          uv run --no-project python tests/support/failed.py junit.xml >> "$GITHUB_STEP_SUMMARY"
+          uv run --no-project python tests/support/failed.py --annotations junit.xml

columbina-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+# A tag like v0.1.0 builds the package, tries it, and publishes it on PyPI. No token is kept
+# anywhere: PyPI trusts this workflow of this repository. That is set up once on pypi.org, in
+# the publishing settings of the project: owner Yueran-ML, repository agent-harness, workflow
+# release.yml, environment pypi.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and try
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: The tag is the version of the package
+        run: |
+          version="$(uv version --short)"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "the tag ${GITHUB_REF_NAME} is not the version ${version} of pyproject.toml"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: The description and the metadata
+        run: uvx twine check --strict dist/*
+
+      # In a clean environment of each Python, with a home of its own and a scripted model.
+      - name: The wheel installs and runs
+        env:
+          PYTHON_KEYRING_BACKEND: keyring.backends.null.Keyring
+        run: |
+          cat > "$RUNNER_TEMP/patch.yml" <<'EOF'
+          - id: model
+            plugin: columbina.llm.adapters.scripted
+            config:
+              provider: deepseek
+              replies:
+                - text: The wheel works.
+          EOF
+          for version in 3.11 3.12; do
+            env="$RUNNER_TEMP/py$version"
+            uv venv --python "$version" "$env"
+            uv pip install --python "$env" dist/*.whl
+            export COLUMBINA_HOME="$RUNNER_TEMP/home$version"
+            "$env/bin/columbina" --version
+            answer="$("$env/bin/columbina" run --patch "$RUNNER_TEMP/patch.yml" \
+              --cwd "$RUNNER_TEMP" "Say whether the wheel works.")"
+            test "$answer" = "The wheel works."
+          done
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish on PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

columbina-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# 工具缓存
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.hypothesis/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# 密钥与日志（运行期数据在 COLUMBINA_HOME，不在项目目录里）
+.env
+.env.*
+!.env.example
+*.log
+# The tasks of the benchmark have logs to work on.
+!bench/tasks/**/*.log
+
+# 编辑器与系统
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

columbina-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

columbina-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes are written down here. The version follows
+[Semantic Versioning](https://semver.org/), and while it is below 1.0 a minor version may
+change what was there before.
+
+## 0.1.0 (2026-10-15)
+
+The first release. It is the work of ten stages, and each of them ended with something that
+could be run.
+
+### The kernel and the agent
+
+- A small asyncio kernel of plugins, with services, scopes and fibers. Everything else is a
+  plugin of it, and a program is a profile: a list of plugin entries that may extend another
+  profile and be patched.
+- The session log: an append-only log of events that is the truth of a session, with
+  projections that are folded from it. A session is taken up again after the program was
+  killed, and can be copied from any of its turns.
+- Models over the OpenAI Chat Completions protocol: DeepSeek, OpenAI, OpenRouter, Moonshot,
+  Zhipu, SiliconFlow, and Ollama and LM Studio on the same machine, or any service by its
+  address. Requests that fail for a passing reason are made again.
+- The tool pipeline and the agent loop: calls are checked, asked about, run, limited and
+  logged; a reply that was cut off is taken up again, and the end of every turn says in a
+  code why it ended.
+
+### Tools, permissions and the sandbox
+
+- Six tools that read, write and edit files, find them, search them and run commands, all
+  through one seam of the file system: a file is changed only after it was read, and a path
+  that leads out of the working directory is asked about.
+- Three presets of permissions, rules of a project and of the user, and a yes at the prompt
+  for one call or for the rest of a session.
+- A sandbox in a Docker container for the commands of the agent: the working directory and
+  nothing else of the machine, no network by default, and what a command leaves running is
+  stopped with it.
+
+### Long conversations and extensions
+
+- An estimate of the size of a conversation, a place for results that are too large to be
+  shown whole, and a summary of the oldest part when the conversation comes near the limit
+  of its model, with what the summary leaves out said to the model.
+- Skills, hooks, subagents, the tools of servers that speak the Model Context Protocol, and
+  plugins of one's own, with an example of a tool.
+
+### Frontends
+
+- A terminal interface, `columbina`, and one task at a time with `columbina run`, which can
+  report the run as lines of JSON.
+- `columbina serve`, a JSON-RPC service over standard input and output, and a desktop
+  application on top of it.
+
+### Measured
+
+- A benchmark of 72 tasks that judge themselves: fixes of code, work on files, queries of a
+  database and reckonings of several steps. Its tables set two models of DeepSeek against
+  each other, each part of the program against the whole of it, and local models in several
+  quantizations against each other. On it `deepseek-flash` passed all 216 attempts at the
+  tasks, three at each, and `deepseek-v4-pro` 214.
+- Line and branch coverage of 100 percent, more than 3,600 mutants that the tests have to
+  notice, pyright in strict mode, and continuous integration on Windows, Linux and macOS
+  with Python 3.11 and 3.12. On Linux the tests with a real Docker engine have to run.

columbina-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yueran Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

columbina-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: columbina
+Version: 0.1.0
+Summary: A plugin-based agent harness for Python.
+Project-URL: Homepage, https://github.com/Yueran-ML/agent-harness
+Project-URL: Documentation, https://github.com/Yueran-ML/agent-harness/blob/main/docs/guide.md
+Project-URL: Repository, https://github.com/Yueran-ML/agent-harness
+Project-URL: Issues, https://github.com/Yueran-ML/agent-harness/issues
+Project-URL: Changelog, https://github.com/Yueran-ML/agent-harness/blob/main/CHANGELOG.md
+Author: Yueran Ma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,asyncio,coding-agent,harness,llm,mcp,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: prompt-toolkit>=3.0.50
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Columbina
+
+**A plugin-based agent harness, written from scratch in Python.**
+
+Columbina runs an agent against a language model and lets it work in a directory of yours.
+The agent reads, searches and changes files and runs commands, and what a call may do is
+decided before it runs. Everything that Columbina is made of is a plugin of a small asyncio
+kernel: the model adapter, the tool registry, the session log, and the agent loop itself.
+
+- A conversation at the terminal, one task from the command line, and a JSON-RPC service
+  for other programs, such as its desktop app.
+- Any model service that speaks the OpenAI Chat Completions protocol; DeepSeek by default,
+  and Ollama and LM Studio on the same machine.
+- Long conversations are made shorter by themselves, and a session can be taken up again
+  after the program was killed.
+- Skills, hooks, subagents and the tools of MCP servers add to the agent without a change
+  to the program.
+- With Docker, the commands of the agent run in a container that has the working directory
+  and no network.
+
+## Install
+
+```bash
+pip install columbina          # or: uv tool install columbina
+pip install "columbina[mcp]"   # with the tools of MCP servers
+```
+
+Columbina needs Python 3.11 or newer.
+
+## First steps
+
+```bash
+columbina setup                 # choose a service and a model, and store the key
+columbina                       # a conversation at the terminal
+columbina run "What does this project do? Answer in three sentences."
+```
+
+## More
+
+The [repository](https://github.com/Yueran-ML/agent-harness) has the source, the
+[guide](https://github.com/Yueran-ML/agent-harness/blob/main/docs/guide.md) (also in
+[简体中文](https://github.com/Yueran-ML/agent-harness/blob/main/docs/guide.zh-CN.md) and
+[日本語](https://github.com/Yueran-ML/agent-harness/blob/main/docs/guide.ja.md)), the
+[engineering report](https://github.com/Yueran-ML/agent-harness/blob/main/docs/report.md), and
+the [tables of the benchmark](https://github.com/Yueran-ML/agent-harness/blob/main/docs/bench/README.md)
+that it is measured with.
+
+Columbina is released under the MIT license.

columbina-0.1.0/README.ja.md

@@ -0,0 +1,133 @@
+<p align="center">
+  <img src="docs/assets/columbina-wings.png" width="100%"
+       alt="満月を背に翼を広げて浮かぶ人影と、その下で静かな水面に立つ廃墟。">
+</p>
+<p align="center">
+  <sub>ファンアートです。画像生成 AI で作成しました。<a href="#コロンビーナについて">画像について</a></sub>
+</p>
+
+<h1 align="center">Columbina</h1>
+
+<p align="center">
+  <strong>Python でゼロから書いた、プラグインベースのエージェントハーネス</strong>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <b>日本語</b>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Yueran-ML/agent-harness/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Yueran-ML/agent-harness/actions/workflows/ci.yml/badge.svg"></a>
+  <img alt="Python 3.11 と 3.12" src="https://img.shields.io/badge/python-3.11%20%7C%203.12-8b7fd6?labelColor=1b1b2f&logo=python&logoColor=white">
+  <img alt="カバレッジ 100%" src="https://img.shields.io/badge/coverage-100%25-8b7fd6?labelColor=1b1b2f">
+  <img alt="型チェック pyright strict モード" src="https://img.shields.io/badge/types-pyright%20strict-8b7fd6?labelColor=1b1b2f">
+  <img alt="リント ruff" src="https://img.shields.io/badge/lint-ruff-8b7fd6?labelColor=1b1b2f">
+  <img alt="ライセンス MIT" src="https://img.shields.io/badge/license-MIT-8b7fd6?labelColor=1b1b2f">
+</p>
+
+<p align="center">
+  <a href="#コロンビーナについて">名前</a> ·
+  <a href="#概要">概要</a> ·
+  <a href="#ダウンロードとセットアップ">ダウンロードとセットアップ</a> ·
+  <a href="#ドキュメント">ドキュメント</a>
+</p>
+
+## コロンビーナについて
+
+このプロジェクトの名前は、『原神』のキャラクター、コロンビーナ（Columbina）に由来します。彼女は、ファデュイの執行官「十一人のファトゥス」の第三位、「少女」として登場します。ほかの執行官と同じく、名前はイタリアの即興喜劇コンメディア・デッラルテの登場人物から取られており、彼女の場合はコロンビーナ（Colombina）です。彼女の物語はナド・クライを舞台とし、月と関わりがあります。ここにある画像のすべてに月が描かれているのはそのためです。2026 年の初めからはプレイアブルキャラクターになっており、法器を使う星 5 の水元素キャラクターです。
+
+画像は、一人のファンが思い描いた彼女の姿です。作者が画像生成 AI の ChatGPT で作成したもので、公式のイラストではありません。各ファイルは生成されたときのまま保存しており、作成方法を示すコンテンツクレデンシャル（Content Credentials）が含まれています。
+
+<p align="center">
+  <img src="docs/assets/columbina-ruins.png" width="100%"
+       alt="水辺の廃墟に座り、両手の間に小さな光を包んでいる同じ人物。">
+</p>
+
+<details>
+<summary>ストーリーボード</summary>
+<br>
+<p align="center">
+  <img src="docs/assets/columbina-storyboard.png" width="100%"
+       alt="同じ人物を描いた十二の小さな場面。Columbina という名前と、そのためのマークが入っています。">
+</p>
+
+この画像の中の文字は、画像の一部です。プログラムの機能の一覧ではありません。
+
+</details>
+
+画像を見て彼女に興味を持った方は、ぜひゲームの中で彼女に会ってみてください。『原神』は基本プレイ無料です。公式サイトは [genshin.hoyoverse.com](https://genshin.hoyoverse.com/) で、中国本土向けの公式サイトは [ys.mihoyo.com](https://ys.mihoyo.com/) です。
+
+『原神』とそのキャラクターは HoYoverse（miHoYo）に帰属します。このプロジェクトはファンによるもので、HoYoverse とは関係がなく、公認も受けていません。画像はソフトウェアの一部ではなく、以下のライセンスの対象外です。詳しくは [`docs/assets`](docs/assets/README.md) をご覧ください。
+
+## 概要
+
+Columbina は、エージェントを言語モデルにつなぎ、指定したディレクトリの中で作業させます。エージェントはファイルの読み取り、検索、変更とコマンドの実行を行い、それぞれの呼び出しに何が許されるかは実行の前に判定されます。Columbina を構成するものはすべて、小さな asyncio カーネルのプラグインです。モデルアダプター、ツールレジストリ、セッションログ、そしてエージェントループ自体もそうです。
+
+**ステータス**：開発の初期です。全十段階のうち七つが完了し、残る三つのうち、ベンチマーク、PyPI パッケージ、ほかのプログラム向けのサービスはでき上がっています。`columbina` はターミナルでエージェントと対話し、`columbina run` はタスクを一つ渡して回答を出力します。エージェントは OpenAI Chat Completions プロトコルでモデルと通信し、既定では DeepSeek を使います。モデルの上限を超えた対話は自動的に圧縮され、プログラムが強制終了された後でもセッションを再開できます。スキル、フック、サブエージェント、MCP サーバーのツールで、プログラムに手を加えずにエージェントを拡張できます。Docker があれば、エージェントのコマンドは、作業ディレクトリだけがありネットワークのないコンテナの中で実行できます。
+
+## ダウンロードとセットアップ
+
+Columbina には Python 3.11 以降と [uv](https://docs.astral.sh/uv/) が必要です。まだ PyPI には公開していないため、git でこのリポジトリをクローンして入手します。
+
+```bash
+git clone https://github.com/Yueran-ML/agent-harness.git
+cd agent-harness
+uv sync
+```
+
+`uv sync` は、クローンの中に仮想環境を作り、Columbina に必要なものをそこにインストールします。
+
+モデルはサービスから提供され、サービスには API キーが必要です。Columbina はその両方を尋ねます。クローンの中で次のコマンドを実行します。
+
+```bash
+uv run columbina setup
+```
+
+どのサービスを使うか、どのモデルを使うか、そしてキーを尋ねます。DeepSeek、OpenAI、OpenRouter、Moonshot、Zhipu、SiliconFlow は名前で選べます。同じマシンで動く Ollama と LM Studio も同様です。OpenAI Chat Completions プロトコルに対応するほかのサービスは、アドレスを指定して追加できます。キーは入力しても画面に表示されません。キーはシステムのキーリングに保存されます。Windows の資格情報マネージャーや macOS のキーチェーンがこれに当たります。システムにキーリングがない場合は、`~/.columbina` の中のファイルに保存されます。保管の方法は[ガイド](docs/guide.ja.md#サービスとキー)で説明しています。
+
+キーは環境変数で渡すこともでき、環境変数は保存したキーより優先されます。何も選んでいない場合、Columbina は DeepSeek に接続し、`DEEPSEEK_API_KEY` を読みます。Windows の PowerShell では次のようにします。
+
+```powershell
+$env:DEEPSEEK_API_KEY = "your-key"
+```
+
+Linux や macOS のシェルでは次のようにします。
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+```
+
+このように設定した変数は、そのウィンドウを閉じるまで有効です。キーはリクエストを送るときに読み取られます。プロファイルや保存されたセッションに書き込まれることはなく、エラーメッセージからも、表示や保存の前に必ず取り除かれます。
+
+クローンの中で次のコマンドを実行すると、ターミナルでの対話が始まります。
+
+```bash
+uv run columbina
+```
+
+コマンドラインでタスクを渡すこともでき、その場合は回答が出力されます。
+
+```bash
+uv run columbina run "What does this project do? Answer in three sentences."
+```
+
+このように起動すると、エージェントはクローン自体の中で作業します。`--cwd DIR` で別のディレクトリを指定できます。どのディレクトリでもコマンドを使えるようにするには、クローンの中で一度インストールします。
+
+```bash
+uv tool install .
+```
+
+以後は、どのディレクトリで `columbina` を実行しても、そのディレクトリで対話が始まります。シェルがコマンドを見つけられない場合は、`uv tool update-shell` を実行すると、uv がコマンドをインストールするディレクトリが PATH に追加されます。後で `git pull` をしたときは、`uv tool install . --reinstall` でコマンドを最新にします。
+
+## ドキュメント
+
+- [ガイド](docs/guide.ja.md)では、そのほかのことを説明しています。ターミナルとそのコマンド、長い対話、単一タスクの実行、サービスとキー、権限、スキル、フック、サブエージェント、ツールサーバー、Columbina のアーキテクチャ、テストの方法、進捗です。
+- [エンジニアリングレポート](docs/report.md)では、Columbina の組み立て、形を決めた選択、テストの方法、性能を説明しています（[中国語版](docs/report.zh-CN.md)）。
+- [ベンチマークの表](docs/bench/README.md)には、DeepSeek の二つのモデルでの結果、部分ごとの比較、費用があります。
+- [設計文書](docs/plans/2026-10-09-columbina-design.md)は中国語で書かれています。各段階の計画も同じディレクトリにあります。
+- [`docs/research`](docs/research) には、Columbina が手本にしたハーネスから学んだことをまとめています。
+- [`docs/protocol`](docs/protocol) には、デスクトップアプリがプログラムとやり取りするメッセージを記述しています。
+
+## ライセンス
+
+コードとドキュメントには MIT ライセンスを適用します。[LICENSE](LICENSE) をご覧ください。