dominusnode-langchain 1.0.0__tar.gz

dominusnode_langchain-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+dist/
+build/
+*.egg-info/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.DS_Store
+.idea/
+.vscode/
+*.swp

dominusnode_langchain-1.0.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0 (2026-03-01)
+
+- Initial release
+- 5 LangChain tools: proxy fetch, wallet balance, top-up (Stripe), top-up (PayPal), usage stats
+- DominusNodeToolkit for easy integration
+- SSRF protection, credential scrubbing, OFAC compliance

dominusnode_langchain-1.0.0/LICENSE

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

dominusnode_langchain-1.0.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: dominusnode-langchain
+Version: 1.0.0
+Summary: LangChain tools for DomiNode rotating proxy service
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: dominusnode>=0.1.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: langchain-core>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DomiNode LangChain Integration
+
+LangChain tools for the [DomiNode](https://dominusnode.com) rotating proxy-as-a-service platform. Enables LangChain agents to make proxied HTTP requests, check wallet balances, monitor usage, and query proxy configuration through the DomiNode network.
+
+## Installation
+
+```bash
+pip install dominusnode-langchain
+```
+
+Or install from source:
+
+```bash
+cd integrations/langchain
+pip install -e ".[dev]"
+```
+
+### Dependencies
+
+- `langchain-core >= 0.2.0`
+- `dominusnode >= 0.1.0` (DomiNode Python SDK)
+- `httpx >= 0.24.0`
+
+## Quick Start
+
+### Environment Variables
+
+Set up your DomiNode credentials:
+
+```bash
+export DOMINUSNODE_API_KEY="dn_live_your_api_key_here"
+export DOMINUSNODE_BASE_URL="https://api.dominusnode.com"   # optional, this is the default
+export DOMINUSNODE_PROXY_HOST="proxy.dominusnode.com"       # optional, this is the default
+```
+
+### Basic Usage with a LangChain Agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_core.prompts import ChatPromptTemplate
+
+from dominusnode_langchain import DominusNodeToolkit
+
+# Initialize the toolkit (reads DOMINUSNODE_API_KEY from env)
+toolkit = DominusNodeToolkit()
+tools = toolkit.get_tools()
+
+# Set up a LangChain agent
+llm = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant with access to a proxy network."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_tool_calling_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+# Run the agent
+result = executor.invoke({
+    "input": "Check my proxy balance, then fetch https://httpbin.org/ip through a US proxy"
+})
+print(result["output"])
+```
+
+### Direct Tool Usage
+
+You can also use the tools directly without an agent:
+
+```python
+from dominusnode_langchain import (
+    DominusNodeToolkit,
+    DominusNodeProxiedFetchTool,
+    DominusNodeBalanceTool,
+)
+
+toolkit = DominusNodeToolkit(api_key="dn_live_your_key")
+tools = toolkit.get_tools()
+
+# Get tools by name
+fetch_tool = next(t for t in tools if t.name == "dominusnode_proxied_fetch")
+balance_tool = next(t for t in tools if t.name == "dominusnode_balance")
+
+# Check balance
+print(balance_tool.run({}))
+# Output: Balance: $50.00 (5000 cents)
+#         Currency: usd
+
+# Fetch a URL through a US proxy
+print(fetch_tool.run({
+    "url": "https://httpbin.org/ip",
+    "country": "US",
+    "proxy_type": "dc",
+}))
+# Output: Status: 200
+#         Content-Type: application/json
+#         Body:
+#         { "origin": "203.0.113.42" }
+```
+
+## Tools
+
+### `dominusnode_proxied_fetch`
+
+Makes HTTP requests through the DomiNode rotating proxy network.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | str | *required* | The URL to fetch |
+| `method` | str | `"GET"` | HTTP method (`GET`, `HEAD`, or `OPTIONS`) |
+| `country` | str | `None` | ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`, `"DE"`) |
+| `proxy_type` | str | `"dc"` | `"dc"` for datacenter ($3/GB) or `"residential"` ($5/GB) |
+
+**Security:**
+- Only read-only HTTP methods (GET, HEAD, OPTIONS) are allowed
+- SSRF protection blocks private IPs, localhost, and reserved ranges
+- Response bodies are truncated to 4,000 characters
+- `file://`, `ftp://`, and other non-HTTP schemes are rejected
+- URLs with embedded credentials are rejected
+
+### `dominusnode_balance`
+
+Check your DomiNode wallet balance. No input required.
+
+Returns the balance in both USD and cents.
+
+### `dominusnode_usage`
+
+Check your DomiNode proxy usage statistics. No input required.
+
+Returns total bandwidth used (GB), total cost, and request count.
+
+### `dominusnode_proxy_config`
+
+Get the DomiNode proxy configuration. No input required.
+
+Returns proxy endpoints, supported countries for geo-targeting, blocked countries, rotation intervals, and available geo-targeting features (state, city, ASN).
+
+## Async Usage
+
+All tools support async execution for use with async LangChain agents:
+
+```python
+import asyncio
+from dominusnode_langchain import DominusNodeToolkit
+
+async def main():
+    toolkit = DominusNodeToolkit(api_key="dn_live_your_key")
+    tools = toolkit.get_tools()
+
+    balance_tool = next(t for t in tools if t.name == "dominusnode_balance")
+    fetch_tool = next(t for t in tools if t.name == "dominusnode_proxied_fetch")
+
+    # Async balance check
+    balance = await balance_tool.arun({})
+    print(balance)
+
+    # Async proxied fetch
+    result = await fetch_tool.arun({
+        "url": "https://httpbin.org/headers",
+        "country": "GB",
+    })
+    print(result)
+
+    toolkit.close()
+
+asyncio.run(main())
+```
+
+## Explicit Credentials
+
+If you prefer not to use environment variables:
+
+```python
+from dominusnode_langchain import DominusNodeToolkit
+
+toolkit = DominusNodeToolkit(
+    api_key="dn_live_abc123",
+    base_url="http://localhost:3000",
+    proxy_host="localhost",
+    http_proxy_port=8080,
+    socks5_proxy_port=1080,
+)
+tools = toolkit.get_tools()
+```
+
+## Running Tests
+
+```bash
+cd integrations/langchain
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Pricing Reference
+
+| Proxy Type | Cost to You | Sell Price | Margin |
+|-----------|-------------|------------|--------|
+| Datacenter | $0.012/GB | $3.00/GB | 99.6% |
+| Residential | $4.00/GB | $5.00/GB | 20% |
+
+## License
+
+MIT

dominusnode_langchain-1.0.0/README.md

@@ -0,0 +1,205 @@
+# DomiNode LangChain Integration
+
+LangChain tools for the [DomiNode](https://dominusnode.com) rotating proxy-as-a-service platform. Enables LangChain agents to make proxied HTTP requests, check wallet balances, monitor usage, and query proxy configuration through the DomiNode network.
+
+## Installation
+
+```bash
+pip install dominusnode-langchain
+```
+
+Or install from source:
+
+```bash
+cd integrations/langchain
+pip install -e ".[dev]"
+```
+
+### Dependencies
+
+- `langchain-core >= 0.2.0`
+- `dominusnode >= 0.1.0` (DomiNode Python SDK)
+- `httpx >= 0.24.0`
+
+## Quick Start
+
+### Environment Variables
+
+Set up your DomiNode credentials:
+
+```bash
+export DOMINUSNODE_API_KEY="dn_live_your_api_key_here"
+export DOMINUSNODE_BASE_URL="https://api.dominusnode.com"   # optional, this is the default
+export DOMINUSNODE_PROXY_HOST="proxy.dominusnode.com"       # optional, this is the default
+```
+
+### Basic Usage with a LangChain Agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_core.prompts import ChatPromptTemplate
+
+from dominusnode_langchain import DominusNodeToolkit
+
+# Initialize the toolkit (reads DOMINUSNODE_API_KEY from env)
+toolkit = DominusNodeToolkit()
+tools = toolkit.get_tools()
+
+# Set up a LangChain agent
+llm = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant with access to a proxy network."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_tool_calling_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+# Run the agent
+result = executor.invoke({
+    "input": "Check my proxy balance, then fetch https://httpbin.org/ip through a US proxy"
+})
+print(result["output"])
+```
+
+### Direct Tool Usage
+
+You can also use the tools directly without an agent:
+
+```python
+from dominusnode_langchain import (
+    DominusNodeToolkit,
+    DominusNodeProxiedFetchTool,
+    DominusNodeBalanceTool,
+)
+
+toolkit = DominusNodeToolkit(api_key="dn_live_your_key")
+tools = toolkit.get_tools()
+
+# Get tools by name
+fetch_tool = next(t for t in tools if t.name == "dominusnode_proxied_fetch")
+balance_tool = next(t for t in tools if t.name == "dominusnode_balance")
+
+# Check balance
+print(balance_tool.run({}))
+# Output: Balance: $50.00 (5000 cents)
+#         Currency: usd
+
+# Fetch a URL through a US proxy
+print(fetch_tool.run({
+    "url": "https://httpbin.org/ip",
+    "country": "US",
+    "proxy_type": "dc",
+}))
+# Output: Status: 200
+#         Content-Type: application/json
+#         Body:
+#         { "origin": "203.0.113.42" }
+```
+
+## Tools
+
+### `dominusnode_proxied_fetch`
+
+Makes HTTP requests through the DomiNode rotating proxy network.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | str | *required* | The URL to fetch |
+| `method` | str | `"GET"` | HTTP method (`GET`, `HEAD`, or `OPTIONS`) |
+| `country` | str | `None` | ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`, `"DE"`) |
+| `proxy_type` | str | `"dc"` | `"dc"` for datacenter ($3/GB) or `"residential"` ($5/GB) |
+
+**Security:**
+- Only read-only HTTP methods (GET, HEAD, OPTIONS) are allowed
+- SSRF protection blocks private IPs, localhost, and reserved ranges
+- Response bodies are truncated to 4,000 characters
+- `file://`, `ftp://`, and other non-HTTP schemes are rejected
+- URLs with embedded credentials are rejected
+
+### `dominusnode_balance`
+
+Check your DomiNode wallet balance. No input required.
+
+Returns the balance in both USD and cents.
+
+### `dominusnode_usage`
+
+Check your DomiNode proxy usage statistics. No input required.
+
+Returns total bandwidth used (GB), total cost, and request count.
+
+### `dominusnode_proxy_config`
+
+Get the DomiNode proxy configuration. No input required.
+
+Returns proxy endpoints, supported countries for geo-targeting, blocked countries, rotation intervals, and available geo-targeting features (state, city, ASN).
+
+## Async Usage
+
+All tools support async execution for use with async LangChain agents:
+
+```python
+import asyncio
+from dominusnode_langchain import DominusNodeToolkit
+
+async def main():
+    toolkit = DominusNodeToolkit(api_key="dn_live_your_key")
+    tools = toolkit.get_tools()
+
+    balance_tool = next(t for t in tools if t.name == "dominusnode_balance")
+    fetch_tool = next(t for t in tools if t.name == "dominusnode_proxied_fetch")
+
+    # Async balance check
+    balance = await balance_tool.arun({})
+    print(balance)
+
+    # Async proxied fetch
+    result = await fetch_tool.arun({
+        "url": "https://httpbin.org/headers",
+        "country": "GB",
+    })
+    print(result)
+
+    toolkit.close()
+
+asyncio.run(main())
+```
+
+## Explicit Credentials
+
+If you prefer not to use environment variables:
+
+```python
+from dominusnode_langchain import DominusNodeToolkit
+
+toolkit = DominusNodeToolkit(
+    api_key="dn_live_abc123",
+    base_url="http://localhost:3000",
+    proxy_host="localhost",
+    http_proxy_port=8080,
+    socks5_proxy_port=1080,
+)
+tools = toolkit.get_tools()
+```
+
+## Running Tests
+
+```bash
+cd integrations/langchain
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Pricing Reference
+
+| Proxy Type | Cost to You | Sell Price | Margin |
+|-----------|-------------|------------|--------|
+| Datacenter | $0.012/GB | $3.00/GB | 99.6% |
+| Residential | $4.00/GB | $5.00/GB | 20% |
+
+## License
+
+MIT

dominusnode_langchain-1.0.0/conftest.py

@@ -0,0 +1,105 @@
+"""Mock dominusnode SDK and langchain_core modules before any test imports."""
+import sys
+from typing import Any
+from unittest.mock import MagicMock
+
+from pydantic import BaseModel, ConfigDict
+
+
+# ── Flexible mock types that accept any kwargs ──────────────────────────
+
+class _FlexType:
+    """Base that accepts any keyword arguments."""
+
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+class Wallet(_FlexType):
+    pass
+
+
+class GeoTargeting(_FlexType):
+    pass
+
+
+class ProxyEndpointConfig(_FlexType):
+    pass
+
+
+class ProxyConfig(_FlexType):
+    pass
+
+
+class UsageSummary(_FlexType):
+    pass
+
+
+class UsagePagination(_FlexType):
+    pass
+
+
+class UsagePeriod(_FlexType):
+    pass
+
+
+class UsageResponse(_FlexType):
+    pass
+
+
+class ProxyUrlOptions(_FlexType):
+    pass
+
+
+# Create mock dominusnode module hierarchy
+dominusnode_mock = MagicMock()
+dominusnode_types_mock = MagicMock()
+
+# Wire up types
+dominusnode_types_mock.Wallet = Wallet
+dominusnode_types_mock.GeoTargeting = GeoTargeting
+dominusnode_types_mock.ProxyConfig = ProxyConfig
+dominusnode_types_mock.ProxyEndpointConfig = ProxyEndpointConfig
+dominusnode_types_mock.UsageSummary = UsageSummary
+dominusnode_types_mock.UsagePagination = UsagePagination
+dominusnode_types_mock.UsagePeriod = UsagePeriod
+dominusnode_types_mock.UsageResponse = UsageResponse
+dominusnode_types_mock.ProxyUrlOptions = ProxyUrlOptions
+
+# Wire DominusNodeClient and AsyncDominusNodeClient as MagicMock classes
+dominusnode_mock.DominusNodeClient = MagicMock
+dominusnode_mock.AsyncDominusNodeClient = MagicMock
+dominusnode_mock.types = dominusnode_types_mock
+
+sys.modules.setdefault("dominusnode", dominusnode_mock)
+sys.modules.setdefault("dominusnode.types", dominusnode_types_mock)
+
+
+# ── Mock langchain_core ─────────────────────────────────────────────────
+
+lc_mock = MagicMock()
+lc_tools_mock = MagicMock()
+lc_callbacks_mock = MagicMock()
+
+
+class BaseTool(BaseModel):
+    """Mock langchain_core BaseTool using Pydantic (like real LangChain)."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = ""
+    description: str = ""
+    args_schema: Any = None
+
+
+lc_tools_mock.BaseTool = BaseTool
+lc_callbacks_mock.CallbackManagerForToolRun = MagicMock
+lc_callbacks_mock.AsyncCallbackManagerForToolRun = MagicMock
+
+lc_mock.tools = lc_tools_mock
+lc_mock.callbacks = lc_callbacks_mock
+
+sys.modules.setdefault("langchain_core", lc_mock)
+sys.modules.setdefault("langchain_core.tools", lc_tools_mock)
+sys.modules.setdefault("langchain_core.callbacks", lc_callbacks_mock)

dominusnode_langchain-1.0.0/dominusnode_langchain/__init__.py

@@ -0,0 +1,55 @@
+"""LangChain tools for DomiNode rotating proxy service.
+
+Provides LangChain-compatible tools for making proxied HTTP requests,
+checking wallet balance, viewing usage statistics, and querying proxy
+configuration through the DomiNode platform.
+
+Example::
+
+    from dominusnode_langchain import DominusNodeToolkit
+
+    toolkit = DominusNodeToolkit(api_key="dn_live_...", base_url="http://localhost:3000")
+    tools = toolkit.get_tools()
+
+    # Use with a LangChain agent
+    from langchain.agents import AgentExecutor, create_tool_calling_agent
+    agent = create_tool_calling_agent(llm, tools, prompt)
+"""
+
+from .tools import (
+    DominusNodeAgenticTransactionsTool,
+    DominusNodeAgenticWalletBalanceTool,
+    DominusNodeBalanceTool,
+    DominusNodeCreateAgenticWalletTool,
+    DominusNodeDeleteAgenticWalletTool,
+    DominusNodeFreezeAgenticWalletTool,
+    DominusNodeFundAgenticWalletTool,
+    DominusNodeListAgenticWalletsTool,
+    DominusNodeProxiedFetchTool,
+    DominusNodeProxyConfigTool,
+    DominusNodeTopupPaypalTool,
+    DominusNodeUnfreezeAgenticWalletTool,
+    DominusNodeUpdateWalletPolicyTool,
+    DominusNodeUsageTool,
+    DominusNodeX402InfoTool,
+)
+from .toolkit import DominusNodeToolkit
+
+__all__ = [
+    "DominusNodeToolkit",
+    "DominusNodeProxiedFetchTool",
+    "DominusNodeBalanceTool",
+    "DominusNodeUsageTool",
+    "DominusNodeProxyConfigTool",
+    "DominusNodeTopupPaypalTool",
+    "DominusNodeX402InfoTool",
+    "DominusNodeCreateAgenticWalletTool",
+    "DominusNodeFundAgenticWalletTool",
+    "DominusNodeAgenticWalletBalanceTool",
+    "DominusNodeListAgenticWalletsTool",
+    "DominusNodeAgenticTransactionsTool",
+    "DominusNodeFreezeAgenticWalletTool",
+    "DominusNodeUnfreezeAgenticWalletTool",
+    "DominusNodeDeleteAgenticWalletTool",
+    "DominusNodeUpdateWalletPolicyTool",
+]