[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80969":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":12,"contributorsCount":12,"subscribersCount":12,"size":12,"stars1d":12,"stars7d":12,"stars30d":12,"stars90d":12,"forks30d":12,"starsTrendScore":12,"compositeScore":12,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":14,"fork":14,"defaultBranch":15,"hasWiki":16,"hasPages":14,"topics":17,"createdAt":9,"pushedAt":9,"updatedAt":18,"readmeContent":19,"aiSummary":20,"trendingCount":12,"starSnapshotCount":12,"syncStatus":21,"lastSyncTime":22,"discoverSource":23},80969,"iflow-search-py","zhengyanglsun\u002Fiflow-search-py","zhengyanglsun","Integrate intelligent search capabilities into your Python AI agents via iFlow.",null,"Python",30,0,31,false,"main",true,[],"2026-06-12 02:04:09","# iFlow Search Python SDK\n\nPython SDK for the **iFlow Search API (心流搜索 API)** — web search, image search, and web-page fetching, returning structured data suitable for use by LLMs and AI agents.\n\nThe framework-agnostic core SDK, the MCP adapter, the LangChain adapter, and the OpenAPI tool server all ship from this repository as sibling packages under `packages\u002F`.\n\n## Links\n\n- API docs: \u003Chttps:\u002F\u002Fplatform.iflow.cn\u002Fdocs\u002F>\n- Skill docs: \u003Chttps:\u002F\u002Fplatform.iflow.cn\u002Fdocs\u002Fskill>\n- Official skill repo: \u003Chttps:\u002F\u002Fgithub.com\u002Fiflow-ai\u002Fiflow-skills\u002Ftree\u002Fmain\u002Fskills\u002Fiflow-search>\n- JS SDK repo: \u003Chttps:\u002F\u002Fgithub.com\u002Fzhengyanglsun\u002Fiflow-search-js>\n\n## Status\n\n- ✅ Core SDK implemented (`packages\u002Fiflow-search\u002F`) — published on PyPI as `iflow-search==0.1.0`\n- ✅ Sync and async clients\n- ✅ Real-API smoke verified for all three endpoints\n- ✅ pytest \u002F ruff \u002F mypy strict \u002F `python -m build` all green\n- ✅ MCP adapter (`packages\u002Fiflow-search-mcp\u002F`) — published on PyPI as `iflow-search-mcp==0.1.0`\n- ✅ LangChain adapter (`packages\u002Fiflow-search-langchain\u002F`) — published on PyPI as `iflow-search-langchain==0.1.0`\n- ✅ OpenAPI tool server (`packages\u002Fiflow-search-openapi\u002F`) — published on PyPI as `iflow-search-openapi==0.1.0`\n\n## Installation\n\n```bash\npip install iflow-search\n```\n\nFor local development:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fzhengyanglsun\u002Fiflow-search-py.git\ncd iflow-search-py\u002Fpackages\u002Fiflow-search\npython -m pip install -e \".[dev]\"\n```\n\n## Configuration\n\nSet your API key in the shell environment:\n\n```bash\nexport IFLOW_API_KEY=\"your-api-key\"\n```\n\n**Security**:\n\n- Do not commit API keys.\n- Do not store keys in this README, in tests, in fixtures, in logs, or in `.env` files.\n- The SDK reads `IFLOW_API_KEY` from the shell environment only — never from a file, never from a CLI flag.\n\n## Quickstart — sync\n\n```python\nfrom iflow_search import IFlowSearchClient\n\n# Reads IFLOW_API_KEY from the environment.\nclient = IFlowSearchClient()\n\nweb = client.web_search(query=\"latest LLM benchmarks\", count=3)\nprint(web.results[0].title, web.results[0].url)\n\nimages = client.image_search(query=\"great wall of china\", count=3)\nprint(images.images[0].image_url)\n\npage = client.web_fetch(url=\"https:\u002F\u002Fexample.com\")\nprint(page.title)\n```\n\n## Quickstart — async\n\n```python\nimport asyncio\nfrom iflow_search import AsyncIFlowSearchClient\n\nasync def main() -> None:\n    async with AsyncIFlowSearchClient() as client:\n        web = await client.web_search(query=\"latest LLM benchmarks\", count=3)\n        print(web.results[0].title, web.results[0].url)\n\nasyncio.run(main())\n```\n\n## Capabilities\n\n| Method | Endpoint | Returns |\n|---|---|---|\n| `web_search(query=..., count=None)` | `POST \u002Fapi\u002Fsearch\u002FwebSearch` | `WebSearchResponse` with `.results: list[WebSearchResult]` |\n| `image_search(query=..., count=None)` | `POST \u002Fapi\u002Fsearch\u002FimageSearch` | `ImageSearchResponse` with `.images: list[ImageResult]` |\n| `web_fetch(url=...)` | `POST \u002Fapi\u002Fsearch\u002FwebFetch` | `WebFetchResponse` with `.title`, `.content`, `.from_cache` |\n\nThe Python API uses `query` \u002F `count`; the SDK rewrites them on the wire to `keywords` \u002F `num`. The raw response envelope is always preserved on `response.raw` for callers that need fields the SDK did not model.\n\n## Attribution headers\n\nThe SDK sends the following headers on every request:\n\n| Header | Purpose |\n|---|---|\n| `Authorization` | `Bearer \u003Capi_key>` — built internally from `IFLOW_API_KEY`; not user-overridable |\n| `Content-Type` | `application\u002Fjson` |\n| `Accept` | `application\u002Fjson` |\n| `IFlow-Source` | adapter identifier (default `\"python\"`) |\n| `IFlow-Integration` | package name (default `\"iflow-search\"`) |\n| `IFlow-Integration-Version` | installed package version |\n| `User-Agent` | `\u003Cintegration_name>\u002F\u003Cintegration_version>` |\n\nThe MCP adapter additionally emits, when the host sets the corresponding env vars:\n\n- `IFlow-MCP-Client`\n- `IFlow-MCP-Client-Version`\n\n**The API key is never placed in any attribution header.** Attribution headers exist solely for usage statistics and must remain free of credentials.\n\n## Repository layout\n\n```\niflow-search-py\u002F\n├── docs\u002Fdesign\u002Fpython-sdk-design.md       ← core design document\n├── docs\u002Fdesign\u002Fpython-mcp-design.md       ← MCP adapter design document\n├── docs\u002Fdesign\u002Fpython-langchain-design.md ← LangChain adapter design document\n├── docs\u002Fdesign\u002Fpython-openapi-design.md   ← OpenAPI adapter design document\n├── packages\u002F\n│   ├── iflow-search\u002F                      ← core SDK (PyPI: iflow-search)\n│   │   ├── src\u002Fiflow_search\u002F\n│   │   ├── tests\u002F\n│   │   ├── scripts\u002Fsmoke_real_api.py\n│   │   ├── pyproject.toml\n│   │   ├── README.md                      ← PyPI long_description\n│   │   └── LICENSE\n│   ├── iflow-search-mcp\u002F                  ← MCP stdio server (PyPI: iflow-search-mcp)\n│   │   ├── src\u002Fiflow_search_mcp\u002F\n│   │   ├── tests\u002F\n│   │   ├── scripts\u002Fsmoke_stdio.py\n│   │   ├── pyproject.toml\n│   │   ├── README.md                      ← PyPI long_description\n│   │   └── LICENSE\n│   ├── iflow-search-langchain\u002F            ← LangChain adapter (PyPI: iflow-search-langchain)\n│   │   ├── src\u002Fiflow_search_langchain\u002F\n│   │   ├── tests\u002F\n│   │   ├── scripts\u002Fsmoke_real_api.py\n│   │   ├── pyproject.toml\n│   │   ├── README.md                      ← PyPI long_description\n│   │   └── LICENSE\n│   └── iflow-search-openapi\u002F              ← OpenAPI tool server (PyPI: iflow-search-openapi)\n│       ├── src\u002Fiflow_search_openapi\u002F\n│       ├── tests\u002F\n│       ├── scripts\u002Fsmoke_real_api.py\n│       ├── pyproject.toml\n│       ├── README.md                      ← PyPI long_description\n│       └── LICENSE\n└── .github\u002Fworkflows\u002Fci.yml\n```\n\n## Development commands\n\nFrom `packages\u002Fiflow-search\u002F`:\n\n```bash\npython -m pytest -q                    # 103 offline tests\npython -m ruff check .                 # lint\npython -m mypy src\u002Fiflow_search        # strict typecheck\npython -m build                        # build sdist + wheel into dist\u002F\n```\n\n## Real-API smoke\n\nA separate opt-in script exercises all three endpoints against the live API:\n\n```bash\ncd packages\u002Fiflow-search\nexport IFLOW_API_KEY=\"your-api-key\"\nexport IFLOW_SMOKE=1\npython scripts\u002Fsmoke_real_api.py\n```\n\nThe smoke script:\n\n- Is **opt-in** — without `IFLOW_SMOKE=1` it refuses to call the live API.\n- Reads `IFLOW_API_KEY` from the environment only — never from disk.\n- Redacts the key in all log output.\n- Does not write any file.\n\n## Adapters\n\n### `iflow-search-mcp` — published\n\nMCP stdio server for use by Claude Code, Claude Desktop, Hermes, OpenCode, and other MCP-capable hosts. Exposes `iflow_web_search`, `iflow_image_search`, and `iflow_web_fetch` as MCP tools over the official Python `mcp` SDK.\n\n```bash\npip install iflow-search-mcp\n```\n\nConfigure your MCP host to launch the `iflow-search-mcp` console script. Example for Claude Desktop's `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"iflow-search\": {\n      \"command\": \"iflow-search-mcp\",\n      \"env\": {\n        \"IFLOW_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nRecognised env vars: `IFLOW_API_KEY` (required), `IFLOW_BASE_URL`, `IFLOW_TIMEOUT_MS`, `IFLOW_MCP_CLIENT`, `IFLOW_MCP_CLIENT_VERSION`. The package's own README covers per-host config and the full tool schemas; see `docs\u002Fdesign\u002Fpython-mcp-design.md` for the design rationale.\n\n### `iflow-search-langchain` — published\n\nLangChain `BaseTool` factories for `iflow_web_search`, `iflow_image_search`, and `iflow_web_fetch`. LangGraph consumes these tools directly (`create_react_agent`, `ToolNode`), so there is no separate `iflow-search-langgraph` package.\n\n```bash\npip install iflow-search-langchain\n```\n\n```python\nimport os\nfrom iflow_search_langchain import create_iflow_search_tools\n\ntools = create_iflow_search_tools(api_key=os.environ[\"IFLOW_API_KEY\"])\n# [iflow_web_search, iflow_image_search, iflow_web_fetch] — wire into your agent.\n```\n\nEach tool uses `response_format=\"content_and_artifact\"`: `_run` \u002F `_arun` return `(content: str, artifact: dict)`. Auto-built clients carry `IFlow-Source: langchain` attribution; caller-supplied clients are not mutated. The package's own README covers configuration, attribution, lifecycle, and the LangGraph example; see `docs\u002Fdesign\u002Fpython-langchain-design.md` for the design rationale.\n\n### `iflow-search-openapi` — published\n\nFastAPI \u002F OpenAPI 3.1 tool server for Open WebUI, Coze, and similar platforms that consume OpenAPI tool catalogues. Exposes `iflow_web_search`, `iflow_image_search`, and `iflow_web_fetch` as `POST \u002Ftools\u002F*` endpoints; serves `\u002Fopenapi.json` and `\u002Fhealth`.\n\n```bash\npip install iflow-search-openapi\nexport IFLOW_API_KEY=\"your-api-key\"\niflow-search-openapi\n```\n\nDefault bind is `127.0.0.1:8787` (local-only). Set `IFLOW_OPENAPI_HOST=0.0.0.0` for LAN \u002F container exposure. Optional bearer auth for external callers via `IFLOW_OPENAPI_AUTH_TOKEN`; configurable CORS via `IFLOW_OPENAPI_CORS_ORIGIN`. The package's own README covers configuration and per-platform import flows; see `docs\u002Fdesign\u002Fpython-openapi-design.md` for the design rationale.\n\nSee `docs\u002Fdesign\u002Fpython-sdk-design.md` for the core design rationale.\n\n## License\n\n[MIT](.\u002Fpackages\u002Fiflow-search\u002FLICENSE)\n","iFlow Search Python SDK 是一个用于将智能搜索功能集成到Python AI代理中的库，通过iFlow平台提供网页搜索、图片搜索和网页抓取等服务，并返回适合LLM和AI代理使用的结构化数据。其核心特性包括同步与异步客户端支持、框架无关性设计以及针对所有三个端点的实际API测试验证。此外，项目还提供了MCP适配器、LangChain适配器及OpenAPI工具服务器，以增强其在不同应用场景下的灵活性。适用于需要在网络或图像内容中进行高效信息检索的AI应用开发场景。",2,"2026-06-11 04:03:02","CREATED_QUERY"]