vectorsmith 0.1.0__tar.gz

vectorsmith-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Virtualenv and Python
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+*.so
+
+# Tooling
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.import_linter_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Secrets and local env (keep committed *.example)
+.env
+.env.*
+!.env.example
+
+# Editors and OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+.cursor/
+
+# Unpublished working notes (design dumps, idea PDF)
+.internal/
+
+# Local drafts produced by serve --enable-define
+tools.drafts.yaml
+**/tools.drafts.yaml
+
+# MkDocs
+site/

vectorsmith-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: vectorsmith
+Version: 0.1.0
+Summary: YAML tools for agents: load_tools in-process, or vectorsmith serve as MCP
+Project-URL: Homepage, https://github.com/kjgpta/vectorsmith
+Project-URL: Documentation, https://kjgpta.github.io/vectorsmith/
+Project-URL: Issues, https://github.com/kjgpta/vectorsmith/issues
+Project-URL: Changelog, https://github.com/kjgpta/vectorsmith/blob/main/CHANGELOG.md
+Author: VectorSmith contributors
+License: Apache-2.0
+Keywords: agents,claude,codex,langchain,langgraph,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+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: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: argon2-cffi
+Requires-Dist: httpx
+Requires-Dist: jsonschema
+Requires-Dist: lark
+Requires-Dist: mcp>=1.2
+Requires-Dist: polars>=1.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml
+Requires-Dist: ruamel-yaml
+Requires-Dist: starlette
+Requires-Dist: typer
+Requires-Dist: uvicorn
+Requires-Dist: watchfiles
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.5; extra == 'chroma'
+Requires-Dist: fastembed>=0.3; extra == 'chroma'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
+Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: milvus
+Requires-Dist: fastembed>=0.3; extra == 'milvus'
+Requires-Dist: pymilvus>=2.4; extra == 'milvus'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.2; extra == 'openai-agents'
+Provides-Extra: pgvector
+Requires-Dist: fastembed>=0.3; extra == 'pgvector'
+Requires-Dist: psycopg[binary,pool]>=3.2; extra == 'pgvector'
+Provides-Extra: pinecone
+Requires-Dist: fastembed>=0.3; extra == 'pinecone'
+Requires-Dist: pinecone>=5.0; extra == 'pinecone'
+Provides-Extra: qdrant
+Requires-Dist: fastembed>=0.3; extra == 'qdrant'
+Requires-Dist: qdrant-client>=1.9; extra == 'qdrant'
+Provides-Extra: weaviate
+Requires-Dist: fastembed>=0.3; extra == 'weaviate'
+Requires-Dist: weaviate-client>=4.0; extra == 'weaviate'
+Description-Content-Type: text/markdown
+
+# vectorsmith
+
+Install this package. Write a `tools.yaml`. Use `load_tools` in Python or `vectorsmith serve` as an MCP server.
+
+```bash
+pip install "vectorsmith[qdrant,langchain]"
+```
+
+```python
+from vectorsmith import load_tools
+
+tools = load_tools("tools.yaml")
+```
+
+See the repository `README.md` and `docs/` for integrations and the YAML reference.

vectorsmith-0.1.0/README.md

@@ -0,0 +1,15 @@
+# vectorsmith
+
+Install this package. Write a `tools.yaml`. Use `load_tools` in Python or `vectorsmith serve` as an MCP server.
+
+```bash
+pip install "vectorsmith[qdrant,langchain]"
+```
+
+```python
+from vectorsmith import load_tools
+
+tools = load_tools("tools.yaml")
+```
+
+See the repository `README.md` and `docs/` for integrations and the YAML reference.

vectorsmith-0.1.0/hatch_build.py

@@ -0,0 +1,26 @@
+"""Ship ``vectorsmith_core`` inside the ``vectorsmith`` wheel (not a second PyPI project)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        del version
+        root = Path(self.root)
+        local = root / "vectorsmith_core"
+        sibling = root.parent / "core" / "vectorsmith_core"
+        if (local / "__init__.py").is_file():
+            src = local
+        elif (sibling / "__init__.py").is_file():
+            src = sibling
+        else:
+            raise RuntimeError(
+                "vectorsmith_core not found at ./vectorsmith_core or ../core/vectorsmith_core"
+            )
+        build_data.setdefault("force_include", {})
+        build_data["force_include"][str(src)] = "vectorsmith_core"

vectorsmith-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "vectorsmith"
+version = "0.1.0"
+description = "YAML tools for agents: load_tools in-process, or vectorsmith serve as MCP"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "VectorSmith contributors" }]
+keywords = ["mcp", "langchain", "langgraph", "claude", "codex", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+    "pyyaml",
+    "jsonschema",
+    "polars>=1.0",
+    "lark",
+    "httpx",
+    "typer",
+    "watchfiles",
+    "uvicorn",
+    "starlette",
+    "mcp>=1.2",
+    "argon2-cffi",
+    "ruamel.yaml",
+]
+
+[project.urls]
+Homepage = "https://github.com/kjgpta/vectorsmith"
+Documentation = "https://kjgpta.github.io/vectorsmith/"
+Issues = "https://github.com/kjgpta/vectorsmith/issues"
+Changelog = "https://github.com/kjgpta/vectorsmith/blob/main/CHANGELOG.md"
+
+[project.scripts]
+vectorsmith = "vectorsmith_cli.main:app"
+
+[project.optional-dependencies]
+qdrant = ["qdrant-client>=1.9", "fastembed>=0.3"]
+pgvector = ["psycopg[binary,pool]>=3.2", "fastembed>=0.3"]
+chroma = ["chromadb>=0.5", "fastembed>=0.3"]
+pinecone = ["pinecone>=5.0", "fastembed>=0.3"]
+weaviate = ["weaviate-client>=4.0", "fastembed>=0.3"]
+milvus = ["pymilvus>=2.4", "fastembed>=0.3"]
+langchain = ["langchain-core>=0.3"]
+langgraph = ["langchain-core>=0.3", "langgraph>=0.2"]
+openai-agents = ["openai-agents>=0.2"]
+anthropic = ["anthropic>=0.40"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vectorsmith_cli", "vectorsmith"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"

vectorsmith-0.1.0/vectorsmith/__init__.py

@@ -0,0 +1,31 @@
+"""VectorSmith application API.
+
+In-process (LangChain, LangGraph, OpenAI Agents, Anthropic SDK)::
+
+    from vectorsmith import load_tools   # LangChain / LangGraph
+    from vectorsmith import connect      # call() or .as_openai_agents() / .as_anthropic()
+
+MCP hosts (Claude Desktop, Claude Code, Codex, Cursor)::
+
+    vectorsmith serve tools.yaml --name invoices
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from vectorsmith.runtime import BoundTools, connect
+
+if TYPE_CHECKING:
+    from vectorsmith.langchain_tools import Toolset
+    from vectorsmith.langchain_tools import load_tools as load_tools
+
+__all__ = ["BoundTools", "Toolset", "connect", "load_tools"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in {"load_tools", "Toolset"}:
+        from vectorsmith.langchain_tools import Toolset, load_tools
+
+        return {"load_tools": load_tools, "Toolset": Toolset}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

vectorsmith-0.1.0/vectorsmith/anthropic.py

@@ -0,0 +1,42 @@
+"""Anthropic Messages API tools from a tools.yaml.
+
+    pip install "vectorsmith[qdrant]" anthropic
+    from vectorsmith.anthropic import load_tools
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from vectorsmith.runtime import BoundTools, connect
+
+
+class AnthropicToolset:
+    """``tools`` for ``messages.create``, plus ``execute`` for ``tool_use`` blocks."""
+
+    def __init__(self, bound: BoundTools) -> None:
+        self._bound = bound
+        self.tools = bound.as_anthropic()
+
+    @property
+    def names(self) -> list[str]:
+        return self._bound.names
+
+    async def execute(self, name: str, tool_input: Mapping[str, Any] | None = None) -> str:
+        result = await self._bound.call(name, tool_input)
+        return json.dumps(result)
+
+    async def aclose(self) -> None:
+        await self._bound.aclose()
+
+
+def load_tools(
+    *sources: str | Path | dict[str, Any],
+    env: Mapping[str, str] | None = None,
+    env_file: str | Path | None = None,
+) -> AnthropicToolset:
+    """Compile tools.yaml into Anthropic tool defs + an in-process dispatcher."""
+    return AnthropicToolset(connect(*sources, env=env, env_file=env_file))

vectorsmith-0.1.0/vectorsmith/langchain.py

@@ -0,0 +1,5 @@
+"""LangChain adapter. Same as ``from vectorsmith import load_tools``."""
+
+from vectorsmith.langchain_tools import Toolset, load_tools
+
+__all__ = ["Toolset", "load_tools"]

vectorsmith-0.1.0/vectorsmith/langchain_tools.py

@@ -0,0 +1,110 @@
+"""LangChain / LangGraph tools from a tools.yaml.
+
+Application code: write YAML, then ``from vectorsmith import load_tools``.
+Hosts that cannot import Python (Claude Desktop, Codex, Cursor) use
+``vectorsmith serve`` instead. Same YAML.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from langchain_core.tools import BaseTool, StructuredTool
+from pydantic import BaseModel, Field, create_model
+
+from vectorsmith.runtime import BoundTools, connect
+from vectorsmith_core.api import CallContext
+from vectorsmith_core.execute.engine import Engine
+
+_JSON_TO_PY: dict[str, type] = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+}
+
+
+class Toolset(list[BaseTool]):
+    """LangChain tools plus the engines that back them. Call ``aclose`` when done."""
+
+    def __init__(self, tools: Sequence[BaseTool], engines: Sequence[Engine]) -> None:
+        super().__init__(tools)
+        self._engines = list(engines)
+
+    async def aclose(self) -> None:
+        for engine in self._engines:
+            await engine.aclose()
+
+
+def _py_type(spec: dict[str, Any]) -> type:
+    if spec.get("type") == "array":
+        item = _JSON_TO_PY.get((spec.get("items") or {}).get("type", "string"), str)
+        return list[item]  # type: ignore[valid-type]
+    return _JSON_TO_PY.get(str(spec.get("type", "string")), str)
+
+
+def _args_model(tool_name: str, input_schema: dict[str, Any]) -> type[BaseModel]:
+    props = input_schema.get("properties") or {}
+    required = set(input_schema.get("required") or [])
+    fields: dict[str, Any] = {}
+    for key, spec in props.items():
+        typ = _py_type(spec if isinstance(spec, dict) else {})
+        desc = spec.get("description") if isinstance(spec, dict) else None
+        if key in required:
+            fields[key] = (typ, Field(..., description=desc))
+        else:
+            default = spec.get("default") if isinstance(spec, dict) else None
+            fields[key] = (typ | None, Field(default, description=desc))
+    if not fields:
+        return create_model(f"{tool_name}Args")
+    return create_model(f"{tool_name}Args", **fields)
+
+
+def _bind(engine: Engine, name: str, schema: dict[str, Any]) -> StructuredTool:
+    async def _arun(**kwargs: Any) -> dict[str, Any]:
+        clean = {k: v for k, v in kwargs.items() if v is not None}
+        result = await engine.call(
+            name, clean, ctx=CallContext(request_id=str(uuid.uuid4()))
+        )
+        return result.model_dump()
+
+    def _run(**kwargs: Any) -> dict[str, Any]:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(_arun(**kwargs))
+        raise RuntimeError(f"tool {name!r} must be awaited in an async context")
+
+    return StructuredTool(
+        name=name,
+        description=schema.get("description") or name,
+        args_schema=_args_model(name, schema.get("inputSchema") or {}),
+        coroutine=_arun,
+        func=_run,
+    )
+
+
+def toolset_from_bound(bound: BoundTools) -> Toolset:
+    tools: list[BaseTool] = []
+    for engine in bound._engines:
+        for schema in engine.project.mcp_tool_schemas():
+            tools.append(_bind(engine, str(schema["name"]), schema))
+    return Toolset(tools, bound._engines)
+
+
+def load_tools(
+    *sources: str | Path | dict[str, Any],
+    env: Mapping[str, str] | None = None,
+    env_file: str | Path | None = None,
+) -> Toolset:
+    """Compile one or more tools.yaml files into LangChain / LangGraph tools.
+
+    >>> from vectorsmith import load_tools
+    >>> tools = load_tools("tools.invoices.yaml", "tools.tickets.yaml")
+    >>> # pass ``tools`` into create_agent / create_react_agent; await tools.aclose()
+    """
+    return connect(*sources, env=env, env_file=env_file).as_langchain()

vectorsmith-0.1.0/vectorsmith/langgraph.py

@@ -0,0 +1,5 @@
+"""LangGraph adapter. Same LangChain tools (`ToolNode`, `create_react_agent`)."""
+
+from vectorsmith.langchain_tools import Toolset, load_tools
+
+__all__ = ["Toolset", "load_tools"]

vectorsmith-0.1.0/vectorsmith/openai_agents.py

@@ -0,0 +1,69 @@
+"""OpenAI Agents SDK tools from a tools.yaml.
+
+    pip install "vectorsmith[qdrant,openai-agents]"
+    from vectorsmith.openai_agents import load_tools
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from vectorsmith.runtime import BoundTools, connect
+
+
+class OpenAIAgentToolset(list[Any]):
+    """FunctionTool list plus ``aclose`` for the backing engines."""
+
+    def __init__(self, tools: Sequence[Any], bound: BoundTools) -> None:
+        super().__init__(tools)
+        self._bound = bound
+
+    async def aclose(self) -> None:
+        await self._bound.aclose()
+
+
+def _function_tool(bound: BoundTools, schema: dict[str, Any]) -> Any:
+    try:
+        from agents import FunctionTool
+    except ImportError as exc:
+        raise ImportError(
+            "OpenAI Agents SDK is required. Install with: "
+            'pip install "vectorsmith[openai-agents]"'
+        ) from exc
+
+    name = str(schema["name"])
+    params = schema.get("inputSchema") or {"type": "object", "properties": {}}
+
+    async def _on_invoke(_ctx: Any, raw: str) -> str:
+        try:
+            args = json.loads(raw) if raw else {}
+        except json.JSONDecodeError:
+            args = {}
+        if not isinstance(args, dict):
+            return json.dumps({"error": "tool arguments must be a JSON object"})
+        result = await bound.call(name, args)
+        return json.dumps(result)
+
+    return FunctionTool(
+        name=name,
+        description=schema.get("description") or name,
+        params_json_schema=params,
+        on_invoke_tool=_on_invoke,
+        strict_json_schema=False,
+    )
+
+
+def toolset_from_bound(bound: BoundTools) -> OpenAIAgentToolset:
+    return OpenAIAgentToolset([_function_tool(bound, s) for s in bound.schemas], bound)
+
+
+def load_tools(
+    *sources: str | Path | dict[str, Any],
+    env: Mapping[str, str] | None = None,
+    env_file: str | Path | None = None,
+) -> OpenAIAgentToolset:
+    """Compile tools.yaml into OpenAI Agents SDK ``FunctionTool``s."""
+    return connect(*sources, env=env, env_file=env_file).as_openai_agents()

vectorsmith-0.1.0/vectorsmith/runtime.py

@@ -0,0 +1,139 @@
+"""Compile tools.yaml in-process. Framework adapters wrap this; MCP hosts use ``serve``."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from vectorsmith_core.api import CallContext, EnvCredentialResolver, load_project
+from vectorsmith_core.execute.engine import Engine
+
+
+def _read_env_file(path: Path | None) -> dict[str, str]:
+    if path is None or not path.is_file():
+        return {}
+    out: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        out[key.strip()] = value.strip()
+    return out
+
+
+def _merge_env(
+    env: Mapping[str, str] | None,
+    env_file: str | Path | None,
+) -> dict[str, str]:
+    merged = dict(os.environ)
+    if env:
+        merged.update(env)
+    merged.update(_read_env_file(Path(env_file) if env_file else None))
+    return merged
+
+
+def _one_engine(source: str | Path | dict[str, Any], env: Mapping[str, str]) -> Engine:
+    project = load_project(source, env=env)
+    errors = [i for i in project.issues if i.severity == "error"]
+    if errors:
+        msgs = "; ".join(f"{i.code} {i.message}" for i in errors)
+        raise ValueError(f"tools.yaml failed validation: {msgs}")
+    try:
+        from vectorsmith_core.embed.provider import FastEmbedProvider
+
+        embed: FastEmbedProvider | None = FastEmbedProvider()
+    except Exception:
+        embed = None
+    return Engine(
+        project,
+        credential_resolver=EnvCredentialResolver(env),
+        embed_provider=embed,
+    )
+
+
+class BoundTools:
+    """Compiled YAML tools. Call them directly, or adapt to an agent framework.
+
+    >>> from vectorsmith import connect
+    >>> vs = connect("tools.yaml")
+    >>> await vs.call("search_invoices", {"query": "Globex", "limit": 3})
+    >>> tools = vs.as_langchain()  # pip install 'vectorsmith[langchain]'
+    """
+
+    def __init__(self, engines: Sequence[Engine]) -> None:
+        self._engines = list(engines)
+        self._by_name: dict[str, Engine] = {}
+        schemas: list[dict[str, Any]] = []
+        for engine in self._engines:
+            for schema in engine.project.mcp_tool_schemas():
+                name = str(schema["name"])
+                self._by_name[name] = engine
+                schemas.append(schema)
+        self._schemas = schemas
+
+    @property
+    def names(self) -> list[str]:
+        return [str(s["name"]) for s in self._schemas]
+
+    @property
+    def schemas(self) -> list[dict[str, Any]]:
+        """MCP tool schemas (``name``, ``description``, ``inputSchema``)."""
+        return list(self._schemas)
+
+    def as_anthropic(self) -> list[dict[str, Any]]:
+        """Tool defs for ``anthropic.Anthropic().messages.create(tools=...)``."""
+        return [
+            {
+                "name": s["name"],
+                "description": s.get("description") or s["name"],
+                "input_schema": s.get("inputSchema") or {"type": "object", "properties": {}},
+            }
+            for s in self._schemas
+        ]
+
+    def as_langchain(self) -> Any:
+        """LangChain ``StructuredTool`` list. Requires ``vectorsmith[langchain]``."""
+        from vectorsmith.langchain_tools import toolset_from_bound
+
+        return toolset_from_bound(self)
+
+    def as_openai_agents(self) -> Any:
+        """OpenAI Agents SDK ``FunctionTool`` list. Requires ``vectorsmith[openai-agents]``."""
+        from vectorsmith.openai_agents import toolset_from_bound
+
+        return toolset_from_bound(self)
+
+    async def call(self, name: str, args: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        engine = self._by_name.get(name)
+        if engine is None:
+            known = ", ".join(self.names) or "(none)"
+            raise KeyError(f"unknown tool {name!r}; loaded: {known}")
+        clean = {k: v for k, v in dict(args or {}).items() if v is not None}
+        result = await engine.call(
+            name, clean, ctx=CallContext(request_id=str(uuid.uuid4()))
+        )
+        return result.model_dump()
+
+    async def aclose(self) -> None:
+        for engine in self._engines:
+            await engine.aclose()
+
+
+def connect(
+    *sources: str | Path | dict[str, Any],
+    env: Mapping[str, str] | None = None,
+    env_file: str | Path | None = None,
+) -> BoundTools:
+    """Compile one or more tools.yaml files. No MCP subprocess.
+
+    Use this when you want ``await vs.call(...)`` or a non-LangChain adapter.
+    LangChain / LangGraph apps can keep using ``load_tools``.
+    """
+    if not sources:
+        raise ValueError("connect requires at least one tools.yaml path")
+    merged = _merge_env(env, env_file)
+    return BoundTools([_one_engine(source, merged) for source in sources])

vectorsmith-0.1.0/vectorsmith_cli/__init__.py

@@ -0,0 +1 @@
+"""VectorSmith CLI."""