eo-toolbelt 0.1.0__tar.gz

eo_toolbelt-0.1.0/.pypirc.sample

@@ -0,0 +1,14 @@
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+repository = https://upload.pypi.org/legacy/
+username = __token__
+password = pypi-...
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-...

eo_toolbelt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EO Toolbelt Maintainers
+
+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.

eo_toolbelt-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include README.ko.md
+include PUBLISHING.md
+include PUBLISHING.ko.md
+include LICENSE
+include .pypirc.sample
+include pyproject.toml
+recursive-include scripts *.py
+recursive-include overlays *
+recursive-include examples *.json

eo_toolbelt-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: eo-toolbelt
+Version: 0.1.0
+Summary: Python SDK for EO Toolbelt built-in tools, MCP tools, and provider-native tool schemas
+Author: EO Toolbelt Maintainers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/easyops-io/eo-toolbelt
+Project-URL: Documentation, https://github.com/easyops-io/eo-toolbelt#readme
+Project-URL: Repository, https://github.com/easyops-io/eo-toolbelt
+Project-URL: Issues, https://github.com/easyops-io/eo-toolbelt/issues
+Keywords: mcp,tools,llm,sdk,tool-use
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.8.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: tzdata>=2025.2
+Provides-Extra: dev
+Requires-Dist: setuptools>=69; extra == "dev"
+Requires-Dist: wheel>=0.43; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# EO Toolbelt SDK
+
+Korean documentation: [README.ko.md](README.ko.md)
+
+EO Toolbelt SDK helps Python applications expose utility tools, custom Python functions, and MCP server tools to model providers.
+
+It gives you three small building blocks:
+
+- list available tool specs
+- execute a selected tool by name
+- build provider-native tool option payloads for OpenAI, Anthropic, Gemini, and Bedrock Converse
+
+The SDK does not call a language model for you. Your application keeps the model message loop and passes tool results back using the provider's normal API format.
+
+## Install
+
+```bash
+pip install eo-toolbelt
+```
+
+Import package:
+
+```python
+from mcp_tools_sdk import Tools
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+from mcp_tools_sdk import Tools
+
+
+async def main() -> None:
+    tools = Tools()
+
+    result = await tools.call_tool(
+        "safe_calculate",
+        {"expression": "(12 + 8) * 3"},
+    )
+    print(result)
+
+
+asyncio.run(main())
+```
+
+## Build Model Tool Options
+
+```python
+from openai import AsyncOpenAI
+from mcp_tools_sdk import Tools
+
+client = AsyncOpenAI()
+tools = Tools()
+
+tool_options = await tools.model_tool_options(
+    provider="openai",
+    tool_names=["safe_calculate", "get_current_datetime"],
+)
+
+response = await client.responses.create(
+    model="gpt-5",
+    input="What is 12 * 8, and what time is it in Seoul?",
+    **tool_options,
+)
+```
+
+If the model returns a tool call, parse the provider response, call `tools.call_tool(...)`, then send the tool result back to the model.
+
+## Tools Constructor
+
+```python
+tools = Tools(
+    config_path="mcp_servers.json",
+    timeout_seconds=30,
+    custom_tools=[my_custom_tool],
+)
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `config_path` | `str | Path | None` | MCP server config path. When omitted, built-in and custom tools are available without MCP discovery. |
+| `timeout_seconds` | `float | None` | Timeout for MCP operations. |
+| `custom_tools` | iterable | Python callables or `CustomTool` objects registered on this instance. |
+| `backend` | internal backend | Alternate runtime backend for tests and advanced embedding. |
+
+## Main Methods
+
+### `list_tools(...)`
+
+Returns canonical tool specs.
+
+```python
+catalog = await tools.list_tools(
+    include_internal=True,
+    include_mcp=True,
+    include_custom=True,
+    mcp_server_names=["fetch"],
+    selected_tool_names=["safe_calculate"],
+)
+```
+
+### `call_tool(tool_name, arguments=None)`
+
+Executes one built-in, custom, or MCP tool.
+
+```python
+result = await tools.call_tool(
+    "safe_calculate",
+    {"expression": "7 * 6"},
+)
+```
+
+MCP tools use this name format:
+
+```text
+mcp__{server_name}__{tool_name}
+```
+
+### `model_tool_options(provider, ...)`
+
+Converts tool specs into provider-native request fields.
+
+```python
+tool_options = await tools.model_tool_options(
+    provider="bedrock",
+    tool_names=["safe_calculate"],
+    tool_choice={"auto": {}},
+)
+```
+
+| Provider value | Returned fields |
+| --- | --- |
+| `openai`, `gpt`, `openai_responses` | OpenAI Responses API `tools` and optional `tool_choice`. |
+| `openai_chat_completions` | OpenAI Chat Completions `tools` and optional `tool_choice`. |
+| `anthropic`, `claude` | Anthropic Messages `tools` and optional `tool_choice`. |
+| `gemini` | Gemini `tools` with `function_declarations` and optional `tool_config`. |
+| `bedrock`, `bedrock_converse` | Bedrock Converse `toolConfig`. |
+
+### `select_tools(query, ...)`
+
+Selects a compact tool list from a catalog. Pass an LLM callback for model-judged selection, or omit `llm` for the deterministic keyword fallback.
+
+```python
+tool_names = await tools.select_tools(
+    query="Calculate actual vs budget variance by department.",
+    max_tools=4,
+    llm=select_with_llm,
+)
+```
+
+## Custom Tools
+
+```python
+from typing import Literal
+
+from mcp_tools_sdk import Tools, custom_tool
+
+
+def apply_discount(amount: float, rate: float = 0.1) -> dict:
+    """Apply a discount rate."""
+    return {"amount": amount, "rate": rate, "total": amount * (1 - rate)}
+
+
+@custom_tool(name="classify_priority")
+def classify_priority(level: Literal["low", "high"]) -> str:
+    """Classify a priority level."""
+    return level.upper()
+
+
+tools = Tools(custom_tools=[apply_discount, classify_priority])
+```
+
+## MCP Config
+
+Pass an MCP config file when your application wants to expose MCP server tools:
+
+```python
+tools = Tools(config_path="mcp_servers.json")
+```
+
+An example config is available at [examples/mcp_servers.example.json](examples/mcp_servers.example.json).
+
+Environment variable placeholders use this form:
+
+```text
+${ENV_NAME}
+${ENV_NAME:-default}
+```
+
+Credential values can also be attached to a `Tools` instance:
+
+```python
+tools.configure_integration(
+    "github",
+    {"access_token": "github_pat_..."},
+)
+```
+
+## License
+
+MIT

eo_toolbelt-0.1.0/PUBLISHING.ko.md

@@ -0,0 +1,63 @@
+# 배포 가이드
+
+이 문서는 `eo-toolbelt`를 PyPI에 배포하는 maintainer용 문서입니다.
+
+## 준비
+
+```bash
+cd C:\project\syyoo\eo-toolbelt\packages\eo-toolbelt
+python -m pip install -U pip setuptools wheel build twine
+python scripts\sync_runtime.py
+```
+
+## 검증
+
+```bash
+python -m py_compile (Get-ChildItem -Recurse src -Filter *.py).FullName
+python -m build
+python -m twine check dist\*
+```
+
+isolated build dependency 설치가 제한된 환경에서는 아래 명령을 사용합니다.
+
+```bash
+python -m build --no-isolation
+```
+
+import 확인:
+
+```bash
+python -m venv .venv-test
+.venv-test\Scripts\python -m pip install dist\eo_toolbelt-0.1.0-py3-none-any.whl
+.venv-test\Scripts\python -c "from mcp_tools_sdk import Tools; print(Tools.__name__)"
+```
+
+wheel metadata 확인:
+
+```bash
+python -c "import zipfile; n=zipfile.ZipFile('dist/eo_toolbelt-0.1.0-py3-none-any.whl').namelist(); print(any(x.startswith('mcp_tools_sdk/') for x in n), any(x.startswith('app/') for x in n))"
+```
+
+기대 출력:
+
+```text
+True False
+```
+
+## 업로드
+
+대상 index에 맞게 `.pypirc`를 설정한 뒤 업로드합니다. 예시는 [.pypirc.sample](.pypirc.sample)에 있습니다.
+
+```bash
+python -m twine upload dist\*
+```
+
+TestPyPI:
+
+```bash
+python -m twine upload --repository testpypi dist\*
+```
+
+## 버전 관리
+
+PyPI는 같은 버전의 파일 재업로드를 허용하지 않습니다. 배포 전 `pyproject.toml`의 `version`을 올립니다.

eo_toolbelt-0.1.0/PUBLISHING.md

@@ -0,0 +1,63 @@
+# Publishing
+
+This guide is for maintainers publishing `eo-toolbelt` to PyPI.
+
+## Prepare
+
+```bash
+cd C:\project\syyoo\eo-toolbelt\packages\eo-toolbelt
+python -m pip install -U pip setuptools wheel build twine
+python scripts\sync_runtime.py
+```
+
+## Verify
+
+```bash
+python -m py_compile (Get-ChildItem -Recurse src -Filter *.py).FullName
+python -m build
+python -m twine check dist\*
+```
+
+If your environment blocks isolated build dependency installation, use:
+
+```bash
+python -m build --no-isolation
+```
+
+Quick import check:
+
+```bash
+python -m venv .venv-test
+.venv-test\Scripts\python -m pip install dist\eo_toolbelt-0.1.0-py3-none-any.whl
+.venv-test\Scripts\python -c "from mcp_tools_sdk import Tools; print(Tools.__name__)"
+```
+
+Wheel metadata check:
+
+```bash
+python -c "import zipfile; n=zipfile.ZipFile('dist/eo_toolbelt-0.1.0-py3-none-any.whl').namelist(); print(any(x.startswith('mcp_tools_sdk/') for x in n), any(x.startswith('app/') for x in n))"
+```
+
+Expected output:
+
+```text
+True False
+```
+
+## Upload
+
+Use a `.pypirc` configured for the target index. See [.pypirc.sample](.pypirc.sample).
+
+```bash
+python -m twine upload dist\*
+```
+
+For TestPyPI:
+
+```bash
+python -m twine upload --repository testpypi dist\*
+```
+
+## Versioning
+
+Increase `version` in `pyproject.toml` before every PyPI upload. PyPI does not allow replacing an existing file for the same version.

eo_toolbelt-0.1.0/README.ko.md

@@ -0,0 +1,203 @@
+# EO Toolbelt SDK
+
+English documentation: [README.md](README.md)
+
+EO Toolbelt SDK는 Python 애플리케이션에서 유틸리티 도구, 사용자 정의 Python 함수, MCP 서버 도구를 모델 provider에 연결할 수 있게 해주는 SDK입니다.
+
+주요 기능은 세 가지입니다.
+
+- 사용 가능한 tool spec 조회
+- 선택한 도구 이름으로 실행
+- OpenAI, Anthropic, Gemini, Bedrock Converse 형식의 tool option 생성
+
+SDK가 언어 모델을 직접 호출하지는 않습니다. 모델 호출 흐름은 애플리케이션 코드가 유지하고, SDK는 도구 schema와 실행 결과를 제공합니다.
+
+## 설치
+
+```bash
+pip install eo-toolbelt
+```
+
+import 패키지:
+
+```python
+from mcp_tools_sdk import Tools
+```
+
+## 빠른 시작
+
+```python
+import asyncio
+
+from mcp_tools_sdk import Tools
+
+
+async def main() -> None:
+    tools = Tools()
+
+    result = await tools.call_tool(
+        "safe_calculate",
+        {"expression": "(12 + 8) * 3"},
+    )
+    print(result)
+
+
+asyncio.run(main())
+```
+
+## 모델 Tool Option 생성
+
+```python
+from openai import AsyncOpenAI
+from mcp_tools_sdk import Tools
+
+client = AsyncOpenAI()
+tools = Tools()
+
+tool_options = await tools.model_tool_options(
+    provider="openai",
+    tool_names=["safe_calculate", "get_current_datetime"],
+)
+
+response = await client.responses.create(
+    model="gpt-5",
+    input="What is 12 * 8, and what time is it in Seoul?",
+    **tool_options,
+)
+```
+
+모델이 tool call을 반환하면 provider 응답에서 도구 이름과 인자를 읽고 `tools.call_tool(...)`을 호출한 뒤, 결과를 다시 모델에 전달하면 됩니다.
+
+## Tools 생성자
+
+```python
+tools = Tools(
+    config_path="mcp_servers.json",
+    timeout_seconds=30,
+    custom_tools=[my_custom_tool],
+)
+```
+
+| 옵션 | 타입 | 설명 |
+| --- | --- | --- |
+| `config_path` | `str | Path | None` | MCP 서버 설정 파일 경로입니다. 생략하면 built-in/custom 도구를 MCP discovery 없이 사용할 수 있습니다. |
+| `timeout_seconds` | `float | None` | MCP 작업 timeout입니다. |
+| `custom_tools` | iterable | 이 인스턴스에 등록할 Python callable 또는 `CustomTool` 객체입니다. |
+| `backend` | internal backend | 테스트와 고급 embedding을 위한 대체 runtime backend입니다. |
+
+## 주요 메서드
+
+### `list_tools(...)`
+
+표준 tool spec 목록을 반환합니다.
+
+```python
+catalog = await tools.list_tools(
+    include_internal=True,
+    include_mcp=True,
+    include_custom=True,
+    mcp_server_names=["fetch"],
+    selected_tool_names=["safe_calculate"],
+)
+```
+
+### `call_tool(tool_name, arguments=None)`
+
+built-in, custom, MCP 도구 중 하나를 실행합니다.
+
+```python
+result = await tools.call_tool(
+    "safe_calculate",
+    {"expression": "7 * 6"},
+)
+```
+
+MCP 도구 이름은 아래 형식을 사용합니다.
+
+```text
+mcp__{server_name}__{tool_name}
+```
+
+### `model_tool_options(provider, ...)`
+
+tool spec을 provider별 모델 호출 필드로 변환합니다.
+
+```python
+tool_options = await tools.model_tool_options(
+    provider="bedrock",
+    tool_names=["safe_calculate"],
+    tool_choice={"auto": {}},
+)
+```
+
+| Provider 값 | 반환 필드 |
+| --- | --- |
+| `openai`, `gpt`, `openai_responses` | OpenAI Responses API `tools`와 선택적 `tool_choice`. |
+| `openai_chat_completions` | OpenAI Chat Completions `tools`와 선택적 `tool_choice`. |
+| `anthropic`, `claude` | Anthropic Messages `tools`와 선택적 `tool_choice`. |
+| `gemini` | Gemini `function_declarations` 기반 `tools`와 선택적 `tool_config`. |
+| `bedrock`, `bedrock_converse` | Bedrock Converse `toolConfig`. |
+
+### `select_tools(query, ...)`
+
+카탈로그에서 작은 도구 목록을 선택합니다. LLM callback을 넘기면 모델 기반 선택을 사용하고, 생략하면 deterministic keyword fallback을 사용합니다.
+
+```python
+tool_names = await tools.select_tools(
+    query="Calculate actual vs budget variance by department.",
+    max_tools=4,
+    llm=select_with_llm,
+)
+```
+
+## Custom Tools
+
+```python
+from typing import Literal
+
+from mcp_tools_sdk import Tools, custom_tool
+
+
+def apply_discount(amount: float, rate: float = 0.1) -> dict:
+    """Apply a discount rate."""
+    return {"amount": amount, "rate": rate, "total": amount * (1 - rate)}
+
+
+@custom_tool(name="classify_priority")
+def classify_priority(level: Literal["low", "high"]) -> str:
+    """Classify a priority level."""
+    return level.upper()
+
+
+tools = Tools(custom_tools=[apply_discount, classify_priority])
+```
+
+## MCP 설정
+
+MCP 서버 도구를 연결하려면 MCP 설정 파일을 전달합니다.
+
+```python
+tools = Tools(config_path="mcp_servers.json")
+```
+
+예시는 [examples/mcp_servers.example.json](examples/mcp_servers.example.json)에 있습니다.
+
+환경변수 placeholder는 아래 형식을 사용합니다.
+
+```text
+${ENV_NAME}
+${ENV_NAME:-default}
+```
+
+인증 값은 `Tools` 인스턴스에 직접 연결할 수도 있습니다.
+
+```python
+tools.configure_integration(
+    "github",
+    {"access_token": "github_pat_..."},
+)
+```
+
+## 라이선스
+
+MIT