weni-utils-tools 0.0.1__tar.gz

weni_utils_tools-0.0.1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-02-01
+
+### Added
+- Initial release of weni-utils-tools
+- `ProductConcierge` - Main class for product search orchestration
+- `VTEXClient` - VTEX API client with intelligent search, cart simulation, and regionalization
+- `StockManager` - Stock availability verification and filtering
+- `SearchContext` - Shared context for plugin communication
+
+### Plugins
+- `Regionalization` - Postal code-based region and seller selection
+- `Wholesale` - Wholesale pricing (minQuantity, valueAtacado)
+- `Carousel` - WhatsApp carousel message formatting and sending
+- `CAPI` - Meta Conversions API integration
+- `WeniFlowTrigger` - Weni flow triggering
+
+### Documentation
+- Complete README with usage examples
+- Example implementations for agents

weni_utils_tools-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Weni AI
+
+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.

weni_utils_tools-0.0.1/MANIFEST.in

@@ -0,0 +1,26 @@
+# Include essential files
+include LICENSE
+include README.md
+include CHANGELOG.md
+include py.typed
+
+# Include source files
+recursive-include src *.py
+recursive-include src *.pyi
+
+# Include tests
+recursive-include tests *.py
+
+# Exclude compiled files
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude *.so
+global-exclude .DS_Store
+
+# Exclude development files
+exclude .gitignore
+exclude .pre-commit-config.yaml
+prune .github
+prune .git
+prune examples
+prune docs

weni_utils_tools-0.0.1/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: weni-utils-tools
+Version: 0.0.1
+Summary: Modular tools library for AI agents on the Weni platform
+Author-email: Weni AI <dev@weni.ai>
+Maintainer-email: Weni AI <dev@weni.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/weni-ai/tools-utils
+Project-URL: Documentation, https://github.com/weni-ai/tools-utils#readme
+Project-URL: Repository, https://github.com/weni-ai/tools-utils.git
+Project-URL: Issues, https://github.com/weni-ai/tools-utils/issues
+Project-URL: Changelog, https://github.com/weni-ai/tools-utils/blob/main/CHANGELOG.md
+Keywords: weni,vtex,ecommerce,ai-agent,chatbot,whatsapp,product-search,intelligent-search,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0.0,>=2.28.0
+Requires-Dist: pytz>=2023.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: black==24.10.0; extra == "dev"
+Requires-Dist: isort==5.13.2; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Dynamic: license-file
+
+# Weni Tools
+
+Modular tools library for AI agents on the Weni platform.
+
+## 📦 Installation
+
+```bash
+pip install weni-utils-tools
+```
+
+> **Note**: The package name on PyPI is `weni-utils-tools` (with hyphens), and you import it as `weni_utils.tools`:
+> - Install: `pip install weni-utils-tools`
+> - Import: `from weni_utils.tools import ...`
+
+## 🎯 Problem Solved
+
+Before this library, each client had a complete copy of the agent code, resulting in:
+- ❌ Duplicated code (70%+ identical between clients)
+- ❌ Bug fix = N manual deploys
+- ❌ Exponential maintenance
+- ❌ Difficult onboarding of new clients
+
+## ✅ Solution
+
+A centralized library with plugin system:
+- ✅ Shared core (search, simulation, stock)
+- ✅ Optional plugins (regionalization, wholesale, carousel)
+- ✅ Bug fix = 1 deploy, all updated
+- ✅ New client = import and configure plugins
+
+## 🚀 Basic Usage
+
+### Modular Functions (Recommended)
+
+```python
+from weni_utils.tools import search_products, get_region, simulate_cart
+
+# Search products
+products = search_products(
+    base_url="https://store.vtexcommercestable.com.br",
+    product_name="drill",
+    max_products=10
+)
+
+# Get region by postal code
+region_id, error, sellers = get_region(
+    base_url="https://store.vtexcommercestable.com.br",
+    postal_code="01310-100"
+)
+
+# Simulate cart
+result = simulate_cart(
+    base_url="https://store.vtexcommercestable.com.br",
+    items=[{"id": "61556", "quantity": 1, "seller": "1"}],
+    postal_code="01310-100"
+)
+```
+
+### Orchestration Class
+
+```python
+from weni_utils.tools import ProductConcierge
+
+concierge = ProductConcierge(
+    base_url="https://store.vtexcommercestable.com.br",
+    store_url="https://store.com.br"
+)
+
+result = concierge.search(product_name="drill")
+```
+
+## 🔌 Available Plugins
+
+### Regionalization
+For clients with postal code-based regionalization.
+
+```python
+from weni_utils.tools import ProductConcierge
+from weni_utils.tools.plugins import Regionalization
+
+concierge = ProductConcierge(
+    base_url="...",
+    store_url="...",
+    plugins=[
+        Regionalization()
+    ]
+)
+
+result = concierge.search(
+    product_name="cement",
+    postal_code="01310-100"
+)
+```
+
+### Wholesale
+For clients with wholesale pricing.
+
+```python
+from weni_utils.tools.plugins import Wholesale
+
+concierge = ProductConcierge(
+    plugins=[
+        Wholesale(fixed_price_url="https://store.com.br/fixedprices")
+    ]
+)
+```
+
+### Carousel
+For sending products via WhatsApp carousel.
+
+```python
+from weni_utils.tools.plugins import Carousel
+
+concierge = ProductConcierge(
+    plugins=[
+        Carousel(
+            weni_token="your-token",
+            max_items=10,
+            auto_send=True
+        )
+    ]
+)
+
+result = concierge.search(
+    product_name="shirt",
+    contact_info={"urn": "whatsapp:5511999999999"}
+)
+```
+
+### CAPI (Meta Conversions API)
+For sending conversion events to Meta.
+
+```python
+from weni_utils.tools.plugins import CAPI
+
+concierge = ProductConcierge(
+    plugins=[
+        CAPI(event_type="lead", auto_send=True)
+    ]
+)
+```
+
+### WeniFlowTrigger
+For triggering Weni flows.
+
+```python
+from weni_utils.tools.plugins import WeniFlowTrigger
+
+concierge = ProductConcierge(
+    plugins=[
+        WeniFlowTrigger(
+            flow_uuid="flow-uuid",
+            trigger_once=True
+        )
+    ]
+)
+```
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        ProductConcierge                              │
+│                     (Orchestrates entire flow)                       │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+            ┌────────────────────┼────────────────────┐
+            │                    │                    │
+            ▼                    ▼                    ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│   VTEXClient    │  │  StockManager   │  │    Plugins      │
+│                 │  │                 │  │                 │
+│ • search()      │  │ • check()       │  │ • before_search │
+│ • simulate()    │  │ • filter()      │  │ • after_search  │
+│ • get_region()  │  │ • limit_size()  │  │ • enrich()      │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+```
+
+## 🔄 Execution Flow
+
+1. **before_search** - Plugins modify context (e.g., get region_id)
+2. **intelligent_search** - Search products in VTEX
+3. **after_search** - Plugins filter/modify products
+4. **check_availability** - Verify stock
+5. **after_stock_check** - Plugins enrich (e.g., wholesale prices)
+6. **filter_products** - Filter only products with stock
+7. **enrich_products** - Plugins add extra data
+8. **finalize_result** - Plugins perform final actions (e.g., send events)
+
+## 🤝 Creating a New Plugin
+
+```python
+from weni_utils.tools.plugins import PluginBase
+
+class MyPlugin(PluginBase):
+    name = "my_plugin"
+    
+    def before_search(self, context, client):
+        # Modify context before search
+        return context
+    
+    def after_search(self, products, context, client):
+        # Modify products after search
+        return products
+    
+    def after_stock_check(self, products_with_stock, context, client):
+        # Enrich products after stock check
+        return products_with_stock
+    
+    def finalize_result(self, result, context):
+        # Final modification before return
+        return result
+```
+
+## 📝 License
+
+MIT License - Weni AI

weni_utils_tools-0.0.1/README.md

@@ -0,0 +1,217 @@
+# Weni Tools
+
+Modular tools library for AI agents on the Weni platform.
+
+## 📦 Installation
+
+```bash
+pip install weni-utils-tools
+```
+
+> **Note**: The package name on PyPI is `weni-utils-tools` (with hyphens), and you import it as `weni_utils.tools`:
+> - Install: `pip install weni-utils-tools`
+> - Import: `from weni_utils.tools import ...`
+
+## 🎯 Problem Solved
+
+Before this library, each client had a complete copy of the agent code, resulting in:
+- ❌ Duplicated code (70%+ identical between clients)
+- ❌ Bug fix = N manual deploys
+- ❌ Exponential maintenance
+- ❌ Difficult onboarding of new clients
+
+## ✅ Solution
+
+A centralized library with plugin system:
+- ✅ Shared core (search, simulation, stock)
+- ✅ Optional plugins (regionalization, wholesale, carousel)
+- ✅ Bug fix = 1 deploy, all updated
+- ✅ New client = import and configure plugins
+
+## 🚀 Basic Usage
+
+### Modular Functions (Recommended)
+
+```python
+from weni_utils.tools import search_products, get_region, simulate_cart
+
+# Search products
+products = search_products(
+    base_url="https://store.vtexcommercestable.com.br",
+    product_name="drill",
+    max_products=10
+)
+
+# Get region by postal code
+region_id, error, sellers = get_region(
+    base_url="https://store.vtexcommercestable.com.br",
+    postal_code="01310-100"
+)
+
+# Simulate cart
+result = simulate_cart(
+    base_url="https://store.vtexcommercestable.com.br",
+    items=[{"id": "61556", "quantity": 1, "seller": "1"}],
+    postal_code="01310-100"
+)
+```
+
+### Orchestration Class
+
+```python
+from weni_utils.tools import ProductConcierge
+
+concierge = ProductConcierge(
+    base_url="https://store.vtexcommercestable.com.br",
+    store_url="https://store.com.br"
+)
+
+result = concierge.search(product_name="drill")
+```
+
+## 🔌 Available Plugins
+
+### Regionalization
+For clients with postal code-based regionalization.
+
+```python
+from weni_utils.tools import ProductConcierge
+from weni_utils.tools.plugins import Regionalization
+
+concierge = ProductConcierge(
+    base_url="...",
+    store_url="...",
+    plugins=[
+        Regionalization()
+    ]
+)
+
+result = concierge.search(
+    product_name="cement",
+    postal_code="01310-100"
+)
+```
+
+### Wholesale
+For clients with wholesale pricing.
+
+```python
+from weni_utils.tools.plugins import Wholesale
+
+concierge = ProductConcierge(
+    plugins=[
+        Wholesale(fixed_price_url="https://store.com.br/fixedprices")
+    ]
+)
+```
+
+### Carousel
+For sending products via WhatsApp carousel.
+
+```python
+from weni_utils.tools.plugins import Carousel
+
+concierge = ProductConcierge(
+    plugins=[
+        Carousel(
+            weni_token="your-token",
+            max_items=10,
+            auto_send=True
+        )
+    ]
+)
+
+result = concierge.search(
+    product_name="shirt",
+    contact_info={"urn": "whatsapp:5511999999999"}
+)
+```
+
+### CAPI (Meta Conversions API)
+For sending conversion events to Meta.
+
+```python
+from weni_utils.tools.plugins import CAPI
+
+concierge = ProductConcierge(
+    plugins=[
+        CAPI(event_type="lead", auto_send=True)
+    ]
+)
+```
+
+### WeniFlowTrigger
+For triggering Weni flows.
+
+```python
+from weni_utils.tools.plugins import WeniFlowTrigger
+
+concierge = ProductConcierge(
+    plugins=[
+        WeniFlowTrigger(
+            flow_uuid="flow-uuid",
+            trigger_once=True
+        )
+    ]
+)
+```
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        ProductConcierge                              │
+│                     (Orchestrates entire flow)                       │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+            ┌────────────────────┼────────────────────┐
+            │                    │                    │
+            ▼                    ▼                    ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│   VTEXClient    │  │  StockManager   │  │    Plugins      │
+│                 │  │                 │  │                 │
+│ • search()      │  │ • check()       │  │ • before_search │
+│ • simulate()    │  │ • filter()      │  │ • after_search  │
+│ • get_region()  │  │ • limit_size()  │  │ • enrich()      │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+```
+
+## 🔄 Execution Flow
+
+1. **before_search** - Plugins modify context (e.g., get region_id)
+2. **intelligent_search** - Search products in VTEX
+3. **after_search** - Plugins filter/modify products
+4. **check_availability** - Verify stock
+5. **after_stock_check** - Plugins enrich (e.g., wholesale prices)
+6. **filter_products** - Filter only products with stock
+7. **enrich_products** - Plugins add extra data
+8. **finalize_result** - Plugins perform final actions (e.g., send events)
+
+## 🤝 Creating a New Plugin
+
+```python
+from weni_utils.tools.plugins import PluginBase
+
+class MyPlugin(PluginBase):
+    name = "my_plugin"
+    
+    def before_search(self, context, client):
+        # Modify context before search
+        return context
+    
+    def after_search(self, products, context, client):
+        # Modify products after search
+        return products
+    
+    def after_stock_check(self, products_with_stock, context, client):
+        # Enrich products after stock check
+        return products_with_stock
+    
+    def finalize_result(self, result, context):
+        # Final modification before return
+        return result
+```
+
+## 📝 License
+
+MIT License - Weni AI

weni_utils_tools-0.0.1/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "weni-utils-tools"
+version = "0.0.1"
+description = "Modular tools library for AI agents on the Weni platform"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Weni AI", email = "dev@weni.ai"}
+]
+maintainers = [
+    {name = "Weni AI", email = "dev@weni.ai"}
+]
+keywords = [
+    "weni",
+    "vtex",
+    "ecommerce",
+    "ai-agent",
+    "chatbot",
+    "whatsapp",
+    "product-search",
+    "intelligent-search",
+    "tools"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Communications :: Chat",
+    "Typing :: Typed"
+]
+
+dependencies = [
+    "requests>=2.28.0,<3.0.0",
+    "pytz>=2023.3"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+    "responses>=0.23.0",
+    "black==24.10.0",
+    "isort==5.13.2",
+    "mypy>=1.0.0",
+    "types-requests>=2.28.0",
+    "ruff>=0.1.0"
+]
+docs = [
+    "sphinx>=6.0.0",
+    "sphinx-rtd-theme>=1.2.0",
+    "myst-parser>=1.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/weni-ai/tools-utils"
+Documentation = "https://github.com/weni-ai/tools-utils#readme"
+Repository = "https://github.com/weni-ai/tools-utils.git"
+Issues = "https://github.com/weni-ai/tools-utils/issues"
+Changelog = "https://github.com/weni-ai/tools-utils/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["weni_utils*"]
+
+[tool.setuptools.package-data]
+"weni_utils.tools" = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py39", "py310", "py311", "py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+known_first_party = ["weni_utils"]
+skip_gitignore = true
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = false
+no_implicit_optional = false
+strict_optional = false
+allow_untyped_globals = true
+ignore_errors = false
+
+[[tool.mypy.overrides]]
+module = "weni_utils.*"
+ignore_errors = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --cov=weni_utils --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["src/weni_utils"]
+branch = true

weni_utils_tools-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

weni_utils_tools-0.0.1/src/weni_utils/__init__.py

@@ -0,0 +1,7 @@
+"""
+Weni - AI Agent Tools Library
+
+A modular library for building AI agents on the Weni platform.
+"""
+
+__version__ = "0.0.1"