Metadata-Version: 2.4
Name: panofy
Version: 0.6.0
Summary: Python SDK for Panofy Agent Platform
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# Panofy Python SDK

Python SDK for the Panofy Agent Platform.

## Installation

```bash
pip install panofy
```

## Quick Start

```python
from panofy import Panofy

panofy = Panofy(
    agent_id="your-agent-id",
    api_key="da_your_api_key",
)

result = panofy.predict(input="hello")
print(result)

# Inspect token usage and point cost from the last predict run.
print(panofy.last_usage())       # cache_read, cache_write, output_token
print(panofy.last_point_usage()) # points_consumed

# Pass multiple Agent input fields directly as keyword arguments.
summary = panofy.predict(
    title="AI 入门",
    language="zh-CN",
    max_length=200,
)

# String values that point to existing local files are uploaded automatically
# and rewritten to task-visible filenames in FUNC_INPUT.json.
report = panofy.predict(
    claim_application_file="./Claims_application-C2104.json",
)

# Disable output-side file downloads while still returning parsed FUNC_OUTPUT.json.
raw_report = panofy.predict(
    claim_application_file="./Claims_application-C2104.json",
    output_dir=None,
)

# Bound the wait time and best-effort abort the task server-side on timeout.
bounded = panofy.predict(
    input="hello",
    timeout=600.0,
)
```

`predict()` uploads `FUNC_INPUT.json`, starts the BFF plan→execute pipeline via
`/api/sdk/predict-async`, polls `/api/sdk/runs/{run_id}` until the SDK run reaches
a terminal status, then downloads and returns parsed `FUNC_OUTPUT.json`. After a
terminal run, `panofy.last_usage()` returns the latest token usage as
`cache_read`, `cache_write`, and `output_token` when returned by the API;
`panofy.last_point_usage()` returns `points_consumed`. Use
`predict_with_metadata(...)` when you want the parsed output and run metadata
(`run_id`, `task_id`, points, and usage) in one return value.

```python
result = panofy.predict_with_metadata(input="hello")
print(result.output)
print(result.run.run_id, result.run.points_consumed, result.run.usage)
```

The client defaults to `https://panofy.ai`. Pass `base_url="http://localhost:3000"`
only for local development or a custom/private deployment.

If an Agent input field name conflicts with SDK controls such as `timeout`,
`output_dir`, `resolve_files`, or `files`, pass one complete dict instead:
`panofy.predict({"timeout": 30, "input": "hello"})`.

## One-shot training

```python
from panofy import train

result = await train(
    api_key="da_your_api_key",
    name="sales analyst",
    model_id="PANOFY_AIR",
    instruction="You are a sales data analyst.",
    training_data=[
        "./training/function_definition.md",
        "./training/FUNC_INPUT.json",
        "./training/FUNC_OUTPUT.json",
    ],
)

print(result.agent_id, result.task_id)
```

## License

MIT
