From 13d9032e972ef3d624a564a5b21d0c9766ec5c3a Mon Sep 17 00:00:00 2001
From: Alexander Ng <114757545+alexngys@users.noreply.github.com>
Date: Thu, 27 Feb 2025 21:42:56 +0000
Subject: [PATCH] feat: Add Valyu Integration (#17892)

---
 .../tools/llama-index-tools-valyu/.gitignore  | 153 ++++++++++++++++++
 .../tools/llama-index-tools-valyu/BUILD       |   3 +
 .../llama-index-tools-valyu/CHANGELOG.md      |   5 +
 .../tools/llama-index-tools-valyu/Makefile    |  17 ++
 .../tools/llama-index-tools-valyu/README.md   |  31 ++++
 .../llama-index-tools-valyu/examples/BUILD    |   1 +
 .../examples/context.py                       |  22 +++
 .../llama_index/tools/valyu/BUILD             |   1 +
 .../llama_index/tools/valyu/__init__.py       |   3 +
 .../llama_index/tools/valyu/base.py           |  80 +++++++++
 .../llama-index-tools-valyu/pyproject.toml    |  64 ++++++++
 .../tools/llama-index-tools-valyu/tests/BUILD |   1 +
 .../llama-index-tools-valyu/tests/__init__.py |   0
 .../tests/test_tools_valyu.py                 |   7 +
 14 files changed, 388 insertions(+)
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/.gitignore
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/BUILD
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/CHANGELOG.md
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/Makefile
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/README.md
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/examples/BUILD
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/examples/context.py
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/BUILD
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/__init__.py
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/base.py
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/pyproject.toml
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/tests/BUILD
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/tests/__init__.py
 create mode 100644 llama-index-integrations/tools/llama-index-tools-valyu/tests/test_tools_valyu.py

diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/.gitignore b/llama-index-integrations/tools/llama-index-tools-valyu/.gitignore
new file mode 100644
index 000000000..990c18de2
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/.gitignore
@@ -0,0 +1,153 @@
+llama_index/_static
+.DS_Store
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+etc/
+include/
+lib/
+lib64/
+parts/
+sdist/
+share/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+notebooks/
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+pyvenv.cfg
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Jetbrains
+.idea
+modules/
+*.swp
+
+# VsCode
+.vscode
+
+# pipenv
+Pipfile
+Pipfile.lock
+
+# pyright
+pyrightconfig.json
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/BUILD b/llama-index-integrations/tools/llama-index-tools-valyu/BUILD
new file mode 100644
index 000000000..0896ca890
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/BUILD
@@ -0,0 +1,3 @@
+poetry_requirements(
+    name="poetry",
+)
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/CHANGELOG.md b/llama-index-integrations/tools/llama-index-tools-valyu/CHANGELOG.md
new file mode 100644
index 000000000..835ce7def
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/CHANGELOG.md
@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## [0.1.0] - 2025-02-11
+
+- Initial release
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/Makefile b/llama-index-integrations/tools/llama-index-tools-valyu/Makefile
new file mode 100644
index 000000000..b9eab05aa
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/Makefile
@@ -0,0 +1,17 @@
+GIT_ROOT ?= $(shell git rev-parse --show-toplevel)
+
+help:	## Show all Makefile targets.
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[33m%-30s\033[0m %s\n", $$1, $$2}'
+
+format:	## Run code autoformatters (black).
+	pre-commit install
+	git ls-files | xargs pre-commit run black --files
+
+lint:	## Run linters: pre-commit (black, ruff, codespell) and mypy
+	pre-commit install && git ls-files | xargs pre-commit run --show-diff-on-failure --files
+
+test:	## Run tests via pytest.
+	pytest tests
+
+watch-docs:	## Build and watch documentation.
+	sphinx-autobuild docs/ docs/_build/html --open-browser --watch $(GIT_ROOT)/llama_index/
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/README.md b/llama-index-integrations/tools/llama-index-tools-valyu/README.md
new file mode 100644
index 000000000..a6daf0ac5
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/README.md
@@ -0,0 +1,31 @@
+# LlamaIndex Tools Integration: Valyu
+
+This tool connects to [Valyu](https://www.valyu.network/) and its [Exchange Platform](https://exchange.valyu.network/) to easily enable
+your agent to search and get content from programmaticly licensed proprietary content and the web.
+
+To begin, you need to obtain an API key on the [Valyu developer dashboard](https://exchange.valyu.network/user/account/api-keys).
+
+## Usage
+
+Here's an example usage of the ValyuToolSpec.
+
+```python
+# %pip install llama-index llama-index-core llama-index-tools-valyu
+
+from llama_index.tools.valyu import ValyuToolSpec
+from llama_index.agent.openai import OpenAIAgent
+
+valyu_tool = ValyuToolSpec(
+    api_key=os.environ["VALYU_API_KEY"],
+    max_price=100,  # default is 100
+)
+agent = OpenAIAgent.from_tools(valyu_tool.to_tool_list())
+
+agent.chat(
+    "What are the implications of using different volatility calculation methods (EWMA vs. GARCH) in Value at Risk (VaR) modeling for fixed income portfolios?"
+)
+```
+
+`context`: Search for a list of documents relating to a natural language query from programmaticly licensed proprietary content and the web.
+
+This loader is designed to be used as a way to load data as a Tool in a Agent.
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/examples/BUILD b/llama-index-integrations/tools/llama-index-tools-valyu/examples/BUILD
new file mode 100644
index 000000000..db46e8d6c
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/examples/BUILD
@@ -0,0 +1 @@
+python_sources()
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/examples/context.py b/llama-index-integrations/tools/llama-index-tools-valyu/examples/context.py
new file mode 100644
index 000000000..849cf7efa
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/examples/context.py
@@ -0,0 +1,22 @@
+# Get OS for environment variables
+import os
+
+# Set up OpenAI
+from llama_index.agent.openai import OpenAIAgent
+from llama_index.tools.valyu import ValyuToolSpec
+
+
+valyu_tool = ValyuToolSpec(
+    api_key=os.environ["VALYU_API_KEY"],
+    max_price=100,  # default is 100
+)
+
+agent = OpenAIAgent.from_tools(
+    valyu_tool.to_tool_list(),
+    verbose=True,
+)
+
+response = agent.chat(
+    "What are the key considerations and empirical evidence for implementing statistical arbitrage strategies using cointegrated pairs trading, specifically focusing on the optimal lookback period for calculating correlation coefficients and the impact of transaction costs on strategy profitability in high-frequency trading environments?"
+)
+print(response)
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/BUILD b/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/BUILD
new file mode 100644
index 000000000..db46e8d6c
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/BUILD
@@ -0,0 +1 @@
+python_sources()
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/__init__.py b/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/__init__.py
new file mode 100644
index 000000000..c50eebb67
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/__init__.py
@@ -0,0 +1,3 @@
+from llama_index.tools.valyu.base import ValyuToolSpec
+
+__all__ = ["ValyuToolSpec"]
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/base.py b/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/base.py
new file mode 100644
index 000000000..695abc254
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/llama_index/tools/valyu/base.py
@@ -0,0 +1,80 @@
+"""Valyu tool spec."""
+
+from typing import List, Optional
+
+from llama_index.core.schema import Document
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+
+
+class ValyuToolSpec(BaseToolSpec):
+    """Valyu tool spec."""
+
+    spec_functions = [
+        "context",
+    ]
+
+    def __init__(
+        self,
+        api_key: str,
+        verbose: bool = False,
+        max_price: Optional[float] = 100,
+    ) -> None:
+        """Initialize with parameters."""
+        from valyu import Valyu
+
+        self.client = Valyu(api_key=api_key)
+        self._verbose = verbose
+        self._max_price = max_price
+
+    def context(
+        self,
+        query: str,
+        search_type: str = "both",
+        data_sources: Optional[List[str]] = None,
+        max_num_results: int = 10,
+        max_price: Optional[float] = None,
+        query_rewrite: bool = True,
+        similarity_threshold: float = 0.5,
+    ) -> List[Document]:
+        """Find relevant programmaticly licensed proprietary content and the web to answer your query.
+
+        Args:
+            query (str): The question or topic to search for
+            search_type (str): Type of sources to search - "proprietary", "web", or "both"
+            data_sources (Optional[List[str]]): Specific indexes to query from
+            max_num_results (int): Maximum number of results to return. Defaults to 10
+            max_price (Optional[float]): Maximum price per content in PCM. Defaults to 100
+            query_rewrite (bool): Whether to rewrite the query to improve results. Defaults to True
+            similarity_threshold (float): Minimum similarity score for results. Defaults to 0.5
+
+        Returns:
+            List[Document]: List of Document objects containing the search results
+        """
+        if max_price is None:
+            max_price = self._max_price
+
+        response = self.client.context(
+            query=query,
+            search_type=search_type,
+            data_sources=data_sources,
+            max_num_results=max_num_results,
+            max_price=max_price,
+            query_rewrite=query_rewrite,
+            similarity_threshold=similarity_threshold,
+        )
+
+        if self._verbose:
+            print(f"[Valyu Tool] Response: {response}")
+
+        return [
+            Document(
+                text=result.content,
+                metadata={
+                    "title": result.title,
+                    "url": result.url,
+                    "source": result.source,
+                    "price": result.price,
+                },
+            )
+            for result in response.results
+        ]
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/pyproject.toml b/llama-index-integrations/tools/llama-index-tools-valyu/pyproject.toml
new file mode 100644
index 000000000..3ae6bc6f6
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/pyproject.toml
@@ -0,0 +1,64 @@
+[build-system]
+build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core"]
+
+[tool.codespell]
+check-filenames = true
+check-hidden = true
+skip = "*.csv,*.html,*.json,*.jsonl,*.pdf,*.txt,*.ipynb"
+
+[tool.llamahub]
+contains_example = false
+import_path = "llama_index.tools.valyu"
+
+[tool.llamahub.class_authors]
+ValyuToolSpec = "alexngys"
+
+[tool.mypy]
+disallow_untyped_defs = true
+exclude = ["_static", "build", "examples", "notebooks", "venv"]
+ignore_missing_imports = true
+python_version = "3.8"
+
+[tool.poetry]
+authors = ["Alex Ng <alexander.ng@valyu.network>"]
+description = "llama-index tools valyu integration"
+exclude = ["**/BUILD"]
+license = "MIT"
+maintainers = ["alexngys"]
+name = "llama-index-tools-valyu"
+readme = "README.md"
+version = "0.1.0"
+
+[tool.poetry.dependencies]
+python = ">=3.9,<4.0"
+valyu = "^1.0.6"
+llama-index-core = "^0.12.0"
+
+[tool.poetry.group.dev.dependencies]
+ipython = "8.10.0"
+jupyter = "^1.0.0"
+mypy = "0.991"
+pre-commit = "3.2.0"
+pylint = "2.15.10"
+pytest = "7.2.1"
+pytest-mock = "3.11.1"
+ruff = "0.0.292"
+tree-sitter-languages = "^1.8.0"
+types-Deprecated = ">=0.1.0"
+types-PyYAML = "^6.0.12.12"
+types-protobuf = "^4.24.0.4"
+types-redis = "4.5.5.0"
+types-requests = "2.28.11.8"
+types-setuptools = "67.1.0.0"
+
+[tool.poetry.group.dev.dependencies.black]
+extras = ["jupyter"]
+version = "<=23.9.1,>=23.7.0"
+
+[tool.poetry.group.dev.dependencies.codespell]
+extras = ["toml"]
+version = ">=v2.2.6"
+
+[[tool.poetry.packages]]
+include = "llama_index/"
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/tests/BUILD b/llama-index-integrations/tools/llama-index-tools-valyu/tests/BUILD
new file mode 100644
index 000000000..dabf212d7
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/tests/BUILD
@@ -0,0 +1 @@
+python_tests()
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/tests/__init__.py b/llama-index-integrations/tools/llama-index-tools-valyu/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/llama-index-integrations/tools/llama-index-tools-valyu/tests/test_tools_valyu.py b/llama-index-integrations/tools/llama-index-tools-valyu/tests/test_tools_valyu.py
new file mode 100644
index 000000000..1e357be79
--- /dev/null
+++ b/llama-index-integrations/tools/llama-index-tools-valyu/tests/test_tools_valyu.py
@@ -0,0 +1,7 @@
+from llama_index.core.tools.tool_spec.base import BaseToolSpec
+from llama_index.tools.valyu import ValyuToolSpec
+
+
+def test_class():
+    names_of_base_classes = [b.__name__ for b in ValyuToolSpec.__mro__]
+    assert BaseToolSpec.__name__ in names_of_base_classes
-- 
GitLab