Metadata-Version: 2.4
Name: harbor-pi-sdk-agent
Version: 0.1.1
Summary: Reusable Harbor custom agent that runs Pi SDK sessions and writes trajectory artifacts.
Author: Kingwl
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/Kingwl/harbor-pi-sdk-agent
Keywords: harbor,pi,agent,atif,trajectory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"

# harbor-pi-sdk-agent

Run the Pi coding agent from Harbor.

Use this package when you want Harbor to launch a Pi SDK agent and collect Harbor-compatible trajectory artifacts.

## Mental Model

`harbor-pi-sdk-agent` is a thin Harbor wrapper around the official Pi coding agent package, `@mariozechner/pi-coding-agent`.

It is not a provider compatibility layer. Pass Pi's `provider/model-id` through to this package, and let the Pi SDK registry decide the built-in model API, base URL, and request headers. Only pass `base_url`, `model_api`, or `provider_headers_json` when you intentionally want to override Pi's built-in provider metadata or connect to a compatible custom endpoint.

## Install

Install this package into the same Python environment or image that runs Harbor.

From a private package index:

```bash
pip install harbor-pi-sdk-agent
```

From this private GitHub repo:

```bash
pip install git+ssh://git@github.com/Kingwl/harbor-pi-sdk-agent.git
```

With `uv`:

```bash
uv pip install git+ssh://git@github.com/Kingwl/harbor-pi-sdk-agent.git
```

Harbor should already be available in that environment. This package is loaded by import path.

## Run

Set the API key for the provider you want to use:

```bash
export OPENAI_API_KEY=...
```

Then pass the agent import path to Harbor:

```bash
harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=openai/gpt-4.1' \
  --agent-kwarg 'api_key_env=OPENAI_API_KEY'
```

For another Pi built-in provider:

```bash
export DEEPSEEK_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=deepseek/deepseek-v4-pro' \
  --agent-kwarg 'api_key_env=DEEPSEEK_API_KEY'
```

For the Pi built-in Kimi Coding provider:

```bash
export KIMI_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=kimi-coding/kimi-for-coding' \
  --agent-kwarg 'api_key_env=KIMI_API_KEY'
```

For a compatible endpoint that is not already described by Pi's provider registry:

```bash
export ANTHROPIC_API_KEY=...

harbor run \
  --agent-import-path harbor_pi_sdk_agent.agent:PiSdkAgent \
  --agent-kwarg 'model_name=anthropic/model-id' \
  --agent-kwarg 'api_key_env=ANTHROPIC_API_KEY' \
  --agent-kwarg 'base_url=https://your-anthropic-compatible-endpoint' \
  --agent-kwarg 'model_api=anthropic-messages'
```

## Launcher Setup

In your Harbor launcher or task wrapper, use:

```text
harbor_pi_sdk_agent.agent:PiSdkAgent
```

Recommended kwargs:

```text
model_name=provider/model-id
api_key_env=PROVIDER_API_KEY
agent_label=pi-sdk
thinking=xhigh
```

Optional kwargs:

```text
base_url=https://...
model_api=anthropic-messages
provider_headers_json={"User-Agent":"..."}
compaction_enabled=0
filtered_events=1
raw_events=0
max_field_chars=200000
```

Recommended artifacts:

```text
/logs/agent/trajectory.json
/logs/agent/trajectory.steps.jsonl
/logs/agent/pi-filtered.jsonl
/logs/agent/pi-sdk-runner.txt
```

Add this only when you explicitly want raw SDK events:

```text
/logs/agent/pi-raw.jsonl
```

## Outputs

- `trajectory.json`: the main Harbor trajectory.
- `trajectory.steps.jsonl`: step-by-step trajectory stream for long or interrupted runs.
- `pi-filtered.jsonl`: compact Pi SDK event log.
- `pi-raw.jsonl`: raw Pi SDK event log when `raw_events=1`.
- `pi-sdk-runner.txt`: concise agent stdout.

## Python Usage

Harbor usually creates the agent from the import path. If you need to construct it in Python:

```python
from harbor_pi_sdk_agent import PiSdkAgent

agent = PiSdkAgent(
    logs_dir=logs_dir,
    model_name="openai/gpt-4.1",
    api_key_env="OPENAI_API_KEY",
)
```

Use this package as a Harbor agent plugin, not as a standalone command-line tool.
