funchub-sdk 0.1.0__tar.gz

funchub_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: funchub-sdk
+Version: 0.1.0
+Summary: FuncHub - A tool registry and dynamic loader for AI agents
+Author: FuncHub Team
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: packaging>=23.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+
+# FuncHub
+
+> ⚠️ **Security Warning**: FuncHub dynamically loads and executes code from remote Git repositories. **Only install tools from sources you trust**, and use in isolated environments.
+
+FuncHub is a bilingual (Python + NestJS) tool registry and dynamic loader designed for AI Agents. It allows developers to publish, discover, install, and dynamically invoke tool functions.
+
+## Features
+
+- **Dual SDKs**: Python SDK + NestJS SDK, sharing the same design philosophy
+- **Semver version management**: Supports `^1.2.3`, `1.x`, `latest`, branch names, etc.
+- **GitHub publishing integration**: Automatic Fork + PR workflow via GitHub API v3
+- **Cache management**: `.version` file tracks installed versions; expired cache auto-refetches
+- **Private registry support**: Supports custom indexes and mirrors via config
+- **Safety confirmation**: Interactive confirmation on install; `--yes` to bypass
+
+---
+
+## Installation
+
+### Python
+
+```bash
+pip install funchub-sdk
+```
+
+### NestJS
+
+```bash
+npm install funchub-nestjs
+```
+
+---
+
+## Quick Start
+
+### 1. Configure GitHub Token
+
+```bash
+# Python
+funchub login --token ghp_xxxxxxxxxxxx
+
+# NestJS
+npx funchub login --token ghp_xxxxxxxxxxxx
+```
+
+### 2. Search for Tools
+
+```bash
+funchub search scraper
+funchub search web
+```
+
+### 3. Install a Tool
+
+```bash
+# Install latest version
+funchub install web_scraper
+
+# Install with version constraint
+funchub install web_scraper@^1.0
+
+# Install development branch
+funchub install web_scraper@main
+```
+
+### 4. List Installed Tools
+
+```bash
+funchub list
+```
+
+### 5. Use a Tool in Code
+
+**Python:**
+```python
+from funchub import FuncHub
+
+hub = FuncHub()
+scraper = hub.load("web_scraper")
+result = scraper(url="https://example.com")
+```
+
+**NestJS:**
+```typescript
+import { FuncHub } from '@funchub/nestjs';
+
+const hub = new FuncHub();
+const scraper = await hub.load('web_scraper');
+const result = await scraper({ url: 'https://example.com' });
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `funchub login --token <PAT>` | Save GitHub Personal Access Token |
+| `funchub config set <key> <value>` | Set configuration (e.g., custom registry) |
+| `funchub publish --version v1.0.0` | Publish current directory as a tool |
+| `funchub publish --version v1.0.0 --force` | Overwrite existing tool with same name |
+| `funchub publish --version v1.0.0 --dry-run` | Preview without actual submission |
+| `funchub search <query>` | Search for tools in the registry |
+| `funchub install <name>@<constraint>` | Install a tool |
+| `funchub list` | List locally installed tools |
+| `funchub update <name>` | Update a tool to latest version |
+| `funchub update --all` | Update all installed tools |
+| `funchub info <name>` | Show tool details |
+| `funchub uninstall <name>` | Remove local tool cache |
+
+---
+
+## Publishing a Tool
+
+1. Create a `funchub.json` or `funchub.yaml` tool definition file in your project root:
+
+```json
+{
+  "name": "my_tool",
+  "description": "My awesome tool",
+  "version": "1.0.0",
+  "entry_point": "src/index:handler",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": { "type": "string" }
+    }
+  }
+}
+```
+
+2. Publish:
+
+```bash
+funchub publish --version v1.0.0
+```
+
+If you have write access to the registry repo, the tool is committed directly. Otherwise, a Fork + PR is automatically created.
+
+---
+
+## Decorator Usage (Python)
+
+```python
+from funchub import funchub_tool
+
+@funchub_tool(
+    name="web_scraper",
+    description="Scrape web page title",
+    version="1.0.0"
+)
+def scrape_url(url: str) -> str:
+    """Scrape the title from a URL."""
+    import requests
+    from bs4 import BeautifulSoup
+    resp = requests.get(url)
+    soup = BeautifulSoup(resp.text, 'html.parser')
+    return soup.title.string if soup.title else "No title found"
+```
+
+---
+
+## License
+
+Apache License 2.0

funchub_sdk-0.1.0/README.md

@@ -0,0 +1,165 @@
+# FuncHub
+
+> ⚠️ **Security Warning**: FuncHub dynamically loads and executes code from remote Git repositories. **Only install tools from sources you trust**, and use in isolated environments.
+
+FuncHub is a bilingual (Python + NestJS) tool registry and dynamic loader designed for AI Agents. It allows developers to publish, discover, install, and dynamically invoke tool functions.
+
+## Features
+
+- **Dual SDKs**: Python SDK + NestJS SDK, sharing the same design philosophy
+- **Semver version management**: Supports `^1.2.3`, `1.x`, `latest`, branch names, etc.
+- **GitHub publishing integration**: Automatic Fork + PR workflow via GitHub API v3
+- **Cache management**: `.version` file tracks installed versions; expired cache auto-refetches
+- **Private registry support**: Supports custom indexes and mirrors via config
+- **Safety confirmation**: Interactive confirmation on install; `--yes` to bypass
+
+---
+
+## Installation
+
+### Python
+
+```bash
+pip install funchub-sdk
+```
+
+### NestJS
+
+```bash
+npm install funchub-nestjs
+```
+
+---
+
+## Quick Start
+
+### 1. Configure GitHub Token
+
+```bash
+# Python
+funchub login --token ghp_xxxxxxxxxxxx
+
+# NestJS
+npx funchub login --token ghp_xxxxxxxxxxxx
+```
+
+### 2. Search for Tools
+
+```bash
+funchub search scraper
+funchub search web
+```
+
+### 3. Install a Tool
+
+```bash
+# Install latest version
+funchub install web_scraper
+
+# Install with version constraint
+funchub install web_scraper@^1.0
+
+# Install development branch
+funchub install web_scraper@main
+```
+
+### 4. List Installed Tools
+
+```bash
+funchub list
+```
+
+### 5. Use a Tool in Code
+
+**Python:**
+```python
+from funchub import FuncHub
+
+hub = FuncHub()
+scraper = hub.load("web_scraper")
+result = scraper(url="https://example.com")
+```
+
+**NestJS:**
+```typescript
+import { FuncHub } from '@funchub/nestjs';
+
+const hub = new FuncHub();
+const scraper = await hub.load('web_scraper');
+const result = await scraper({ url: 'https://example.com' });
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `funchub login --token <PAT>` | Save GitHub Personal Access Token |
+| `funchub config set <key> <value>` | Set configuration (e.g., custom registry) |
+| `funchub publish --version v1.0.0` | Publish current directory as a tool |
+| `funchub publish --version v1.0.0 --force` | Overwrite existing tool with same name |
+| `funchub publish --version v1.0.0 --dry-run` | Preview without actual submission |
+| `funchub search <query>` | Search for tools in the registry |
+| `funchub install <name>@<constraint>` | Install a tool |
+| `funchub list` | List locally installed tools |
+| `funchub update <name>` | Update a tool to latest version |
+| `funchub update --all` | Update all installed tools |
+| `funchub info <name>` | Show tool details |
+| `funchub uninstall <name>` | Remove local tool cache |
+
+---
+
+## Publishing a Tool
+
+1. Create a `funchub.json` or `funchub.yaml` tool definition file in your project root:
+
+```json
+{
+  "name": "my_tool",
+  "description": "My awesome tool",
+  "version": "1.0.0",
+  "entry_point": "src/index:handler",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "input": { "type": "string" }
+    }
+  }
+}
+```
+
+2. Publish:
+
+```bash
+funchub publish --version v1.0.0
+```
+
+If you have write access to the registry repo, the tool is committed directly. Otherwise, a Fork + PR is automatically created.
+
+---
+
+## Decorator Usage (Python)
+
+```python
+from funchub import funchub_tool
+
+@funchub_tool(
+    name="web_scraper",
+    description="Scrape web page title",
+    version="1.0.0"
+)
+def scrape_url(url: str) -> str:
+    """Scrape the title from a URL."""
+    import requests
+    from bs4 import BeautifulSoup
+    resp = requests.get(url)
+    soup = BeautifulSoup(resp.text, 'html.parser')
+    return soup.title.string if soup.title else "No title found"
+```
+
+---
+
+## License
+
+Apache License 2.0

funchub_sdk-0.1.0/funchub/__init__.py

@@ -0,0 +1,3 @@
+from funchub.client import FuncHub
+
+__all__ = ["FuncHub"]

funchub_sdk-0.1.0/funchub/cli.py

@@ -0,0 +1,204 @@
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+import yaml
+
+from funchub.client import FuncHub
+from funchub.exceptions import ConflictError, FuncHubError, ToolNotFoundError, VersionNotFoundError
+from funchub.github_client import load_config, save_config
+from funchub.models import ToolDefinition, ToolVersion
+
+
+@click.group()
+@click.option("--registry", "-r", envvar="FUNCHUB_REGISTRY", help="中央索引 URL")
+@click.option("--token", envvar="GITHUB_TOKEN", help="GitHub PAT")
+@click.pass_context
+def cli(ctx: click.Context, registry: Optional[str], token: Optional[str]) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["hub"] = FuncHub(registry=registry, token=token)
+
+
+@cli.command()
+@click.option("--token", required=True, help="GitHub Personal Access Token")
+def login(token: str) -> None:
+    cfg = load_config()
+    cfg["github_token"] = token
+    save_config(cfg)
+    click.echo("GitHub Token 已保存到 ~/.funchub/config.yaml")
+
+
+@cli.command()
+@click.argument("key")
+@click.argument("value")
+def config(key: str, value: str) -> None:
+    cfg = load_config()
+    cfg[key] = value
+    save_config(cfg)
+    click.echo(f"配置项 {key} 已设置为 {value}")
+
+
+@cli.command()
+@click.option("--version", "ver", required=True, help="发布的版本号")
+@click.option("--force", is_flag=True, help="覆盖同名工具")
+@click.option("--dry-run", is_flag=True, help="预览不实际提交")
+@click.pass_context
+def publish(ctx: click.Context, ver: str, force: bool, dry_run: bool) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    tool_file = Path("funchub-tool.yaml")
+    if not tool_file.exists():
+        click.echo("错误: 当前目录未找到 funchub-tool.yaml", err=True)
+        sys.exit(1)
+    raw = tool_file.read_text(encoding="utf-8")
+    data = yaml.safe_load(raw)
+    is_prerelease = any(tag in ver.lower() for tag in ("alpha", "beta", "rc", "pre"))
+    tv = ToolVersion(
+        version=ver,
+        source_repo=data.get("source_repo", ""),
+        source_ref=data.get("source_ref", f"v{ver}"),
+        dependencies=data.get("dependencies", []),
+        is_prerelease=is_prerelease,
+    )
+    tool_def = ToolDefinition(
+        name=data["name"],
+        description=data.get("description", ""),
+        parameters=data.get("parameters", {"type": "object", "properties": {}}),
+        author=data.get("author", "anonymous"),
+        entry_point=data.get("entry_point", "index:main"),
+        versions=[tv],
+    )
+    try:
+        result = hub.publish(tool_def, force=force, dry_run=dry_run)
+        if dry_run:
+            click.echo(f"[DRY RUN] {result}")
+        else:
+            click.echo(f"发布成功: {result}")
+    except ConflictError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+    except FuncHubError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("query")
+@click.pass_context
+def search(ctx: click.Context, query: str) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    results = hub.search(query)
+    if not results:
+        click.echo("未找到匹配的工具")
+        return
+    for t in results:
+        click.echo(f"{t.name} - {t.description}")
+
+
+@cli.command()
+@click.argument("tool_spec")
+@click.option("--prerelease", is_flag=True, help="包含预发布版本")
+@click.option("--yes", is_flag=True, help="跳过安全确认")
+@click.pass_context
+def install(ctx: click.Context, tool_spec: str, prerelease: bool, yes: bool) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    constraint: Optional[str] = None
+    tool_name = tool_spec
+    if "@" in tool_spec:
+        tool_name, constraint = tool_spec.split("@", 1)
+    try:
+        hub.install(
+            tool_name,
+            constraint=constraint,
+            include_prerelease=prerelease,
+            yes=yes,
+        )
+        click.echo(f"✅ 工具 {tool_name} 安装成功")
+    except (ToolNotFoundError, VersionNotFoundError) as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+    except FuncHubError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command("list")
+@click.pass_context
+def list_tools(ctx: click.Context) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    items = hub.list_installed()
+    if not items:
+        click.echo("未安装任何工具")
+        return
+    for item in items:
+        click.echo(f"{item['name']}@{item['version']} ({item['source_repo']})")
+
+
+@cli.command()
+@click.argument("name", required=False)
+@click.option("--all", "update_all", is_flag=True, help="更新所有工具")
+@click.option("--prerelease", is_flag=True, help="包含预发布版本")
+@click.option("--yes", is_flag=True, help="跳过安全确认")
+@click.pass_context
+def update(
+    ctx: click.Context,
+    name: Optional[str],
+    update_all: bool,
+    prerelease: bool,
+    yes: bool,
+) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    if update_all:
+        results = hub.update_all(include_prerelease=prerelease, yes=yes)
+        if not results:
+            click.echo("所有工具已是最新")
+        for r in results:
+            click.echo(r)
+        return
+    if not name:
+        click.echo("请指定工具名称或使用 --all", err=True)
+        sys.exit(1)
+    try:
+        result = hub.update(name, include_prerelease=prerelease, yes=yes)
+        click.echo(f"✅ 工具 {name} 已更新到 {result}")
+    except FuncHubError as e:
+        click.echo(f"错误: {e}", err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("name")
+@click.pass_context
+def info(ctx: click.Context, name: str) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    tool_def = hub.info(name)
+    if tool_def is None:
+        click.echo(f"工具 '{name}' 未找到")
+        return
+    click.echo(f"名称: {tool_def.name}")
+    click.echo(f"描述: {tool_def.description}")
+    click.echo(f"作者: {tool_def.author}")
+    click.echo(f"入口: {tool_def.entry_point}")
+    click.echo("版本:")
+    for v in tool_def.versions:
+        pre = " (预发布)" if v.is_prerelease else ""
+        click.echo(f"  - {v.version}{pre}")
+
+
+@cli.command()
+@click.argument("name")
+@click.pass_context
+def uninstall(ctx: click.Context, name: str) -> None:
+    hub: FuncHub = ctx.obj["hub"]
+    if hub.uninstall(name):
+        click.echo(f"✅ 工具 {name} 已卸载")
+    else:
+        click.echo(f"工具 {name} 未安装")
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()