Metadata-Version: 2.5
Name: qwenpaw-data-host-core
Version: 0.3.1
Summary: Shared host foundation for QwenPaw-Data.
Project-URL: Homepage, https://github.com/agentscope-ai/QwenPaw-Data
Project-URL: Documentation, https://github.com/agentscope-ai/QwenPaw-Data/tree/main/packages/qwenpaw-data-host-core
Project-URL: Repository, https://github.com/agentscope-ai/QwenPaw-Data
Project-URL: Issues, https://github.com/agentscope-ai/QwenPaw-Data/issues
Project-URL: Changelog, https://github.com/agentscope-ai/QwenPaw-Data/blob/main/CHANGELOG.md
Author: QwenPaw-Data Contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agents,data-analysis,orchestration,sandbox
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: agentscope<2.1,>=2.0.8
Requires-Dist: aiodocker<0.28,>=0.27
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: pydantic<3.0,>=2.13
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: qwenpaw-data-skills<0.4,>=0.3
Requires-Dist: shortuuid<2.0,>=1.0
Provides-Extra: service
Requires-Dist: aiosqlite<1.0,>=0.20; extra == 'service'
Requires-Dist: apscheduler<4.0,>=3.10; extra == 'service'
Requires-Dist: cryptography<51,>=44; extra == 'service'
Requires-Dist: fastapi<1.0,>=0.115; extra == 'service'
Requires-Dist: python-multipart<1.0,>=0.0.18; extra == 'service'
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0; extra == 'service'
Description-Content-Type: text/markdown

# qwenpaw-data-host-core

Shared host foundation for QwenPaw Data.

This package owns the non-HTTP QwenPaw Data host runtime:

- `QwenPawDataHost` runtime handle for `plan`, `execute`, and `run`
- AgentScope agent, toolkit, workspace tools, and prompt templates
- DAG orchestration, session trace storage, and artifact path helpers
- MCP Context Manager timeout and metadata injection helpers
- Context Manager HTTP discovery client used by CLI integrations

Concrete host packages such as `qwenpaw-data-cli` should depend on this package instead of duplicating host orchestration logic.

## Headless service (optional `[service]` extra)

The engine can run as a headless service that any frontend (PawApp, CLI,
third parties) consumes over HTTP + SSE:

```bash
pip install "qwenpaw-data-host-core[service]" uvicorn
QWENPAW_DATA_API_TOKEN=<token> \
uvicorn --factory 'qwenpaw_data.host.core.api.app:create_app' --workers 1
```

The service is single-process (in-process event fan-out); always run one
worker. Without `QWENPAW_DATA_API_TOKEN`, only loopback clients are accepted.

### API surface (`/api/v1`)

| Route | Purpose |
|---|---|
| `POST /sessions` · `GET /sessions` · `GET/PATCH/DELETE /sessions/{id}` | Session lifecycle: create, list (search/filter/sort/pagination), rename, soft-delete |
| `POST /sessions/{sid}/chats` | Start a turn in an existing session: `{"text": ..., "datasource_id": ...}` → `{"chat": {...}}`; 404 without a session, 409 while a turn is active |
| `GET /sessions/{sid}/chats` | List a session's chats |
| `POST /sessions/{sid}/chats/{cid}/stop` | Cancel a running turn |
| `GET /sessions/{sid}/chats/{cid}/events` | SSE stream: replays persisted history, then live events; supports `Last-Event-ID` (or `after_sequence_number`) resume |
| `POST /sessions/{sid}/chats/{cid}/steer` | Inject steering text into the running turn (204; 409 when not active) |
| `POST /sessions/{sid}/chats/{cid}/clarification/answer` | Deliver an `ask_user_question` result to the paused turn |
| `GET/PUT/DELETE /preferences/providers[/{id}]` · `.../models/{id}` · `GET/PUT /preferences/active-models` | Model provider credentials (masked in responses), model overrides, active model selection |
| `GET /datasources` | DataBridge datasource discovery proxied through the service |
| `GET/POST /cron/jobs` · `GET/PUT/DELETE /cron/jobs/{id}` · `POST .../pause|resume|run` | Scheduled agent runs: a cron expression or one-shot time opens a console chat with the configured message/datasource (single-process APScheduler) |

### Storage backends

The service persists sessions/chats/events/preferences through a store
protocol with two interchangeable backends:

- **sqlite (default)**: `<home>/host/host.db` (WAL); point
  `QWENPAW_DATA_DB_URL` at another SQLAlchemy async URL (e.g. postgres).
- **JSON files**: set `QWENPAW_DATA_STORE=json` for the zero-dependency
  file layout (`<home>/host/{chats,sessions,preferences}/`).

A conformance test suite runs every store test against both backends.
When no explicit model is passed, the service resolves the local user's
configured active model from preferences and falls back to env vars.

### SSE stream objects

Each SSE frame carries `id` (dense per-chat sequence number), `event`
(object type), and a JSON body discriminated on `object`:

`response` (created/in_progress/completed/failed/cancelled, terminal frames
close the stream) · `message` / `content` (assistant text, reasoning, tool
calls and outputs, media) · `task_status` (DAG plan snapshots) ·
`biz_event` / `segment` / `artifact.registered` / `followup.generated`
(reserved; producers arrive in later waves).

### Environment variables

- `QWENPAW_DATA_API_TOKEN` — bearer token; unset = loopback-only
- `QWENPAW_DATA_STORE` — `json` to use file-backed stores (default: sqlite)
- `QWENPAW_DATA_DB_URL` — SQLAlchemy async URL (default `sqlite+aiosqlite:///<home>/host/host.db`)
- `QWENPAW_DATA_PREFS_MASTER_SECRET` — hex secret (≥32 bytes) to encrypt stored provider API keys at rest
- `QWENPAW_DATA_CORS_ALLOW_ORIGINS` — comma-separated origins (default loopback)
- `QWENPAW_DATA_STREAM_SSE_HEARTBEAT_SECONDS` — keepalive interval (default 15)
- `QWENPAW_DATA_FOLLOWUP_ENABLED` — `0` disables follow-up question recommendation (default on)
- `QWENPAW_DATA_MODEL_PROVIDER` / `_NAME` / `_API_KEY` / `_BASE_URL` — model config fallback when no active model is set via preferences

Chat and event history persist in the selected backend, so SSE resume
works across service restarts; orphaned running chats are cancelled on
startup.

## Default local state

`qwenpaw-data-host-core` resolves its own local state through
`qwenpaw_data.host.core.paths`; it does not use DataBridge path helpers.

```text
${QWENPAW_DATA_HOME:-~/.qwenpaw-data}/host/
├── .secrets/                              # shared durable Host secrets
└── workspace/
    ├── .mcp                               # shared durable MCP config
    ├── skills/                            # shared durable skills
    ├── sessions/
    │   ├── console/                       # session traces
    │   ├── dag/                           # session DAG snapshots
    │   └── {session_id}/                  # AgentScope context/tool offload
    ├── data/                              # shared durable AgentScope blobs
    └── artifacts/
        └── {session_id}/                  # direct-chat artifacts
            └── {graph_id}/{node_id}/      # optional TaskGraph node scope
```

Directories are created lazily by their writers. The Host does not read or
migrate the historical `${QWENPAW_DATA_HOME}/agents/default` layout.
