Metadata-Version: 2.4
Name: iflow-search-openapi
Version: 0.1.0a0
Summary: OpenAPI 3.1 tool server for iFlow Search (心流搜索) — drop-in for Open WebUI, Coze, and other platforms that consume OpenAPI tool catalogues.
Project-URL: Homepage, https://platform.iflow.cn/
Project-URL: Documentation, https://platform.iflow.cn/docs/
Project-URL: Repository, https://github.com/zhengyanglsun/iflow-search-py
Project-URL: Issues, https://github.com/zhengyanglsun/iflow-search-py/issues
Author: iFlow Search SDK contributors
License: MIT License
        
        Copyright (c) 2026 iFlow Search SDK contributors
        
        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.
License-File: LICENSE
Keywords: ai,coze,iflow,llm,open-webui,openapi,search,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: iflow-search<0.2,>=0.1.0a0
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: uvicorn<1.0,>=0.30
Provides-Extra: dev
Requires-Dist: httpx<1.0,>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Description-Content-Type: text/markdown

# iflow-search-openapi

OpenAPI 3.1 tool server for **iFlow Search (心流搜索)** — exposes `iflow_web_search`, `iflow_image_search`, and `iflow_web_fetch` over plain HTTP so platforms that consume OpenAPI tool catalogues (Open WebUI, Coze, …) can wire them in directly.

- **Core SDK:** [`iflow-search`](https://pypi.org/project/iflow-search/) — this package wraps it; do not skip installing it (it is a transitive dependency, so `pip install` handles it).
- **Sibling adapters:** [`iflow-search-mcp`](https://pypi.org/project/iflow-search-mcp/) (MCP stdio server), [`iflow-search-langchain`](https://pypi.org/project/iflow-search-langchain/) (LangChain tools).
- **API docs:** <https://platform.iflow.cn/docs/>
- **Status:** alpha pre-release (`0.1.0a0`). Requires `pip install --pre`.

## Install

```bash
pip install --pre iflow-search-openapi
```

`--pre` is required while the version is still a PEP 440 prerelease.

## Run

```bash
export IFLOW_API_KEY="your-iflow-api-key"
iflow-search-openapi
```

Output (stderr):

```
[iflow-search-openapi] v0.1.0a0 listening on http://127.0.0.1:8787 — bearer auth DISABLED (open mode)
```

By default the server binds **`127.0.0.1:8787`** — local-only. Set `IFLOW_OPENAPI_HOST=0.0.0.0` to expose it to a LAN or a container network. See [Configuration](#configuration) for the full env list.

## Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/health` | Liveness probe — `{"ok": true, "version": "..."}` |
| `GET` | `/openapi.json` | OpenAPI 3.1 schema (auto-generated from Pydantic models) |
| `POST` | `/tools/iflow_web_search` | `{"query": "...", "count": 3}` |
| `POST` | `/tools/iflow_image_search` | `{"query": "...", "count": 3}` |
| `POST` | `/tools/iflow_web_fetch` | `{"url": "https://example.com"}` |

### Success envelope

```json
{
  "ok": true,
  "data": {
    "query": "latest LLM benchmarks",
    "results": [
      {"title": "...", "url": "https://...", "snippet": "...", "position": 1}
    ],
    "took_ms": 142
  }
}
```

Field names are **snake_case**. The core SDK's `raw` (upstream envelope) is excluded by default — it bloats LLM context for fields the model cannot act on.

### Error envelope

```json
{
  "ok": false,
  "error": {
    "code": "business_rate_limited",
    "message": "Rate limit exceeded.",
    "status_code": 429
  }
}
```

`code` is a stable string; switch on it (not on HTTP status alone) for retry/backoff decisions. The full code table is in [`docs/design/python-openapi-design.md` §8.3](https://github.com/zhengyanglsun/iflow-search-py/blob/main/docs/design/python-openapi-design.md).

## Use with Open WebUI

1. Run `iflow-search-openapi` somewhere Open WebUI can reach (`http://your-host:8787`).
2. In Open WebUI → **Workspace → Tools → Add Tool** (the "OpenAPI Servers" entry), paste `http://your-host:8787/openapi.json`.
3. If you set `IFLOW_OPENAPI_AUTH_TOKEN`, Open WebUI will prompt for it when importing.
4. Open WebUI imports the three tools; assign them to a model/conversation as usual.

If Open WebUI runs in a browser on a different origin from this server, set `IFLOW_OPENAPI_CORS_ORIGIN=https://your-open-webui-host`.

## Use with Coze

1. Run `iflow-search-openapi` somewhere Coze can reach.
2. Coze → **Plugins → Create plugin → Import from OpenAPI** → URL `http://your-host:8787/openapi.json`.
3. Provide the bearer token (`IFLOW_OPENAPI_AUTH_TOKEN`) when prompted.
4. The three tools appear as plugin actions; attach to a bot as usual.

## Authentication

Two distinct credentials:

| Credential | Direction | Source |
|---|---|---|
| `IFLOW_API_KEY` | this server → iFlow API | env, required |
| `IFLOW_OPENAPI_AUTH_TOKEN` | external client → this server | env, optional |

When `IFLOW_OPENAPI_AUTH_TOKEN` is **unset**, the server is open: any caller that can reach the socket can invoke the tools. Intended for local dev or behind a private network / reverse proxy.

When **set**, all routes except `/health` require `Authorization: Bearer <token>`. The compare is constant-time. `/openapi.json` is also gated so the schema (which advertises the server as an iFlow proxy) stays behind the bearer.

`IFLOW_API_KEY` is **never** echoed in any response, log line, OpenAPI schema, or startup banner — only its *presence* is implied by the server having started successfully.

## Configuration

All configuration is via environment variables. **No `.env` loader. No CLI flags. No config file.**

| Variable | Required | Default | Notes |
|---|---|---|---|
| `IFLOW_API_KEY` | yes | — | iFlow API key. Read once at startup, never echoed. |
| `IFLOW_BASE_URL` | no | core default | Override iFlow API base URL (staging/proxy). |
| `IFLOW_TIMEOUT_MS` | no | `30000` | Per-request timeout in milliseconds. |
| `IFLOW_OPENAPI_HOST` | no | `127.0.0.1` | Bind address. Use `0.0.0.0` for LAN/container exposure. |
| `IFLOW_OPENAPI_PORT` | no | `8787` | Bind port. |
| `IFLOW_OPENAPI_AUTH_TOKEN` | no | unset (open mode) | Bearer token required from external callers when set. |
| `IFLOW_OPENAPI_CORS_ORIGIN` | no | unset (no CORS) | `*` or an exact origin (`https://host[:port]`). |
| `IFLOW_OPENAPI_CLIENT` | no | unset | Free-form host name (e.g. `open-webui`). Banner only — not on the wire. |

### Heroku / App Engine / fly.io — bridging `PORT`

This package uses `IFLOW_OPENAPI_PORT` instead of the generic `PORT` so a platform's auto-injected port can't silently take over the bind. If your platform requires `PORT`, bridge it in your start command:

```bash
IFLOW_OPENAPI_PORT="$PORT" IFLOW_OPENAPI_HOST=0.0.0.0 iflow-search-openapi
```

## CORS

`IFLOW_OPENAPI_CORS_ORIGIN`:

- **unset** — no CORS headers; server is intended for same-origin or server-to-server use.
- `*` — wildcard allow-origin.
- `http(s)://host[:port]` — exact-origin allow.

Anything with a path, query, fragment, or non-printable character is rejected at startup with `ConfigError` and exit code 1 — header-injection guard.

Preflight (`OPTIONS`) short-circuits to 204 before the bearer check, so browser-side tool importers (Open WebUI) can complete preflight without a token.

`Access-Control-Allow-Headers` is `Content-Type, Authorization, X-Session-Id`. `X-Session-Id` is allowed for Open WebUI compatibility; the adapter does not read it.

## Attribution

The adapter does not construct any `Authorization`, `IFlow-*`, or `User-Agent` header itself — that's the core SDK's job. Outbound requests to iFlow carry:

| Header | Value |
|---|---|
| `Authorization` | `Bearer <IFLOW_API_KEY>` |
| `IFlow-Source` | `openapi` |
| `IFlow-Integration` | `iflow-search-openapi` |
| `IFlow-Integration-Version` | this package's `__version__` |
| `User-Agent` | `iflow-search-openapi/<version>` |

`IFLOW_OPENAPI_CLIENT` is **not** forwarded as a wire header (that namespace belongs to MCP transports). It appears in the startup banner only.

## What's not included in v0.1.0a0

- TLS termination — put a reverse proxy in front.
- Streaming / SSE / WebSocket — iFlow Search is request/response.
- Per-platform packages (no `iflow-search-open-webui`, no `iflow-search-coze`).
- A public Python embedding API (`build_app(...)` is underscore-prefixed and not part of the contract).
- `.env` file loading, a CLI flag for the API key, or any config file.
- Per-request access logs — operators put a reverse proxy in front for those.

## Public Python surface

```python
from iflow_search_openapi import __version__
```

That is the only supported import in MVP. Internal modules (`_app`, `_routes`, `_auth`, etc.) are underscore-prefixed; they may be reorganised without notice. The stable contract is the **HTTP surface**, not the Python surface.

## Local development

From `packages/iflow-search-openapi/`:

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check .
python -m mypy src/iflow_search_openapi
python -m build
```

## Real-API smoke

```bash
cd packages/iflow-search-openapi
export IFLOW_API_KEY="your-api-key"
export IFLOW_OPENAPI_SMOKE=1
python scripts/smoke_real_api.py
```

The script:

- Is **opt-in** — without `IFLOW_OPENAPI_SMOKE=1` it refuses to call the live API.
- Reads `IFLOW_API_KEY` from the environment only — never from disk.
- Redacts the key in all log output.
- Does not write any file.

## License

[MIT](./LICENSE)
