wappa 0.1.6__tar.gz → 0.1.8__tar.gz

{wappa-0.1.6 → wappa-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wappa
-Version: 0.1.6
+Version: 0.1.8
 Summary: Open Source Framework to develop smart Workflows, Agents and full chat applications through WhatsApp
 Project-URL: Homepage, https://wappa.mimeia.com
 Project-URL: Documentation, https://wappa.mimeia.com/docs

{wappa-0.1.6 → wappa-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wappa"
-version = "0.1.6"
+version = "0.1.8"
 description = "Open Source Framework to develop smart Workflows, Agents and full chat applications through WhatsApp"
 authors = [
     {name = "Sasha Canal", email = "contact@mimeia.com"},

{wappa-0.1.6 → wappa-0.1.8}/uv.lock

@@ -1198,54 +1198,28 @@ wheels = [
 
 [[package]]
 name = "wappa"
-version = "0.1.5"
+version = "0.1.7"
 source = { editable = "." }
 dependencies = [
     { name = "aiofiles" },
     { name = "aiohttp" },
     { name = "fastapi" },
     { name = "hypercorn" },
+    { name = "numpy" },
+    { name = "openai" },
+    { name = "opencv-python-headless" },
+    { name = "pillow" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
     { name = "python-dotenv" },
     { name = "python-multipart" },
+    { name = "redis" },
     { name = "rich" },
+    { name = "sqlmodel" },
     { name = "typer" },
     { name = "uvicorn", extra = ["standard"] },
 ]
 
-[package.optional-dependencies]
-ai = [
-    { name = "numpy" },
-    { name = "openai" },
-]
-all = [
-    { name = "numpy" },
-    { name = "openai" },
-    { name = "opencv-python-headless" },
-    { name = "pillow" },
-    { name = "redis" },
-    { name = "sqlmodel" },
-]
-database = [
-    { name = "sqlmodel" },
-]
-dev = [
-    { name = "black" },
-    { name = "mypy" },
-    { name = "pre-commit" },
-    { name = "pytest" },
-    { name = "pytest-asyncio" },
-    { name = "ruff" },
-]
-media = [
-    { name = "opencv-python-headless" },
-    { name = "pillow" },
-]
-redis = [
-    { name = "redis" },
-]
-
 [package.dev-dependencies]
 dev = [
     { name = "black" },
@@ -1260,30 +1234,22 @@ dev = [
 requires-dist = [
     { name = "aiofiles", specifier = ">=24.1.0" },
     { name = "aiohttp", specifier = ">=3.11.0" },
-    { name = "black", marker = "extra == 'dev'", specifier = ">=25.1.0" },
     { name = "fastapi", specifier = ">=0.115.0" },
     { name = "hypercorn", specifier = ">=0.17.0" },
-    { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },
-    { name = "numpy", marker = "extra == 'ai'", specifier = ">=2.2.0" },
-    { name = "openai", marker = "extra == 'ai'", specifier = ">=1.69.0" },
-    { name = "opencv-python-headless", marker = "extra == 'media'", specifier = ">=4.11.0" },
-    { name = "pillow", marker = "extra == 'media'", specifier = ">=11.1.0" },
-    { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=3.0.0" },
+    { name = "numpy", specifier = ">=2.2.0" },
+    { name = "openai", specifier = ">=1.69.0" },
+    { name = "opencv-python-headless", specifier = ">=4.11.0" },
+    { name = "pillow", specifier = ">=11.1.0" },
     { name = "pydantic", specifier = ">=2.8.0" },
     { name = "pydantic-settings", specifier = ">=2.10.0" },
-    { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.4.0" },
-    { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=1.1.0" },
     { name = "python-dotenv", specifier = ">=1.0.0" },
     { name = "python-multipart", specifier = ">=0.0.6" },
-    { name = "redis", marker = "extra == 'redis'", specifier = ">=5.2.0" },
+    { name = "redis", specifier = ">=5.2.0" },
     { name = "rich", specifier = ">=13.0.0" },
-    { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.9.0" },
-    { name = "sqlmodel", marker = "extra == 'database'", specifier = ">=0.0.24" },
+    { name = "sqlmodel", specifier = ">=0.0.24" },
     { name = "typer", specifier = ">=0.9.0" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.24.0" },
-    { name = "wappa", extras = ["redis", "database", "ai", "media"], marker = "extra == 'all'" },
 ]
-provides-extras = ["redis", "database", "ai", "media", "dev", "all"]
 
 [package.metadata.requires-dev]
 dev = [

wappa-0.1.8/wappa/__init__.py

@@ -0,0 +1,29 @@
+"""
+Wappa - Open Source WhatsApp Business Framework
+
+A clean, modern Python library for building WhatsApp Business applications
+with minimal setup and maximum flexibility.
+
+Clean Import Interface (SRP Compliance):
+- Only framework essentials exposed at top level
+- Domain-specific imports available via wappa.domain paths
+- Follows Clean Architecture principles
+"""
+
+# Framework Essentials Only (SRP: Framework Foundation)
+from .core.wappa_app import Wappa
+from .core.events.event_handler import WappaEventHandler
+from .core.factory import WappaBuilder, WappaPlugin
+
+# Dynamic version from pyproject.toml
+from .core.config.settings import settings
+
+__version__ = settings.version
+
+__all__ = [
+    # Core Framework Components
+    "Wappa",
+    "WappaEventHandler", 
+    "WappaBuilder",
+    "WappaPlugin",
+]

wappa-0.1.8/wappa/cli/examples/init/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "wappa-init"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "wappa>=0.1.6",
+]

wappa-0.1.8/wappa/cli/examples/json_cache_example/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa-0.1.8/wappa/cli/examples/json_cache_example/README.md

@@ -0,0 +1,190 @@
+# Wappa JSON Cache Example
+
+This example demonstrates how to use Wappa's JSON cache backend with a complete WhatsApp bot implementation following SOLID architecture principles.
+
+## Overview
+
+The JSON Cache Example shows how to build a WhatsApp bot that uses JSON file-based caching for:
+- **User Cache**: User profiles and session data (JSON files)
+- **Table Cache**: Message history and structured data (JSON files) 
+- **State Cache**: Application state management (JSON files)
+
+## Architecture
+
+This example follows **SOLID principles** with a modular score-based architecture:
+
+```
+app/
+├── main.py                 # FastAPI application with JSON cache
+├── master_event.py         # Main event handler using SOLID architecture
+├── models/                 # Pydantic data models
+│   └── json_demo_models.py # User, MessageLog, StateHandler, CacheStats
+├── scores/                 # Business logic modules (Single Responsibility)
+│   ├── score_base.py       # Abstract base for all scores
+│   ├── score_user_management.py      # User profile management
+│   ├── score_message_history.py      # Message logging & /HISTORY
+│   ├── score_state_commands.py       # /WAPPA, /EXIT commands
+│   └── score_cache_statistics.py     # /STATS command & monitoring
+└── utils/                  # Utility functions
+    ├── cache_utils.py      # Cache key generation & TTL management
+    └── message_utils.py    # Message parsing & formatting
+```
+
+## Features
+
+### Cache Operations
+- **JSON File Storage**: All data stored in JSON files on disk
+- **TTL Support**: Automatic expiration of cached data
+- **Persistence**: Data survives application restarts
+- **Performance**: Fast file-based operations with JSON serialization
+
+### Available Commands
+- `/WAPPA` - Enter special state mode (cached in state layer)
+- `/EXIT` - Exit special state mode  
+- `/HISTORY` - View your message history (from table cache)
+- `/STATS` - View JSON cache statistics and health
+
+### Score Modules (SOLID Architecture)
+Each score handles a single responsibility:
+
+1. **UserManagementScore**: User profiles, welcome messages
+2. **MessageHistoryScore**: Message logging, history retrieval  
+3. **StateCommandsScore**: State management, special commands
+4. **CacheStatisticsScore**: Cache monitoring, performance metrics
+
+## Configuration
+
+### Environment Variables
+```bash
+# WhatsApp Business API (required)
+WHATSAPP_API_URL=https://graph.facebook.com/v18.0
+WHATSAPP_ACCESS_TOKEN=your_access_token
+WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
+WHATSAPP_VERIFY_TOKEN=your_webhook_verify_token
+WHATSAPP_WEBHOOK_SECRET=your_webhook_secret
+
+# Application Settings
+PORT=8000
+LOG_LEVEL=INFO
+ENVIRONMENT=development
+```
+
+**Note**: No Redis configuration needed - JSON cache uses the file system!
+
+## Running the Example
+
+1. **Install Dependencies**:
+```bash
+cd json_cache_example
+uv sync
+```
+
+2. **Set Environment Variables**:
+```bash
+# Copy and edit .env file with your WhatsApp credentials
+cp .env.example .env
+```
+
+3. **Run the Application**:
+```bash
+uv run python -m app.main
+```
+
+4. **Test via WhatsApp**:
+   - Send any message to get welcomed
+   - Try `/WAPPA` to enter special state
+   - Send `/HISTORY` to view message history  
+   - Send `/STATS` to see JSON cache statistics
+   - Send `/EXIT` to leave special state
+
+## JSON Cache Behavior
+
+### File Structure
+```
+cache_data/
+├── user_cache/
+│   └── user_profile_{phone_number}.json
+├── table_cache/  
+│   └── msg_history_{phone_number}.json
+└── state_cache/
+    └── wappa_state_{phone_number}.json
+```
+
+### Cache Operations
+- **Set**: Creates/updates JSON files with serialized Pydantic models
+- **Get**: Reads and deserializes JSON files back to Pydantic models
+- **Delete**: Removes JSON files from disk
+- **TTL**: Files older than TTL are automatically cleaned up
+
+### Performance Characteristics
+- **Speed**: Fast for small to medium datasets
+- **Persistence**: Data survives restarts and crashes
+- **Scalability**: Good for moderate traffic (hundreds of users)
+- **Reliability**: No external dependencies, always available
+
+## Development
+
+### Adding New Score Modules
+1. Create new score in `app/scores/`
+2. Inherit from `ScoreBase` 
+3. Implement `can_handle()` and `process()` methods
+4. Register in `master_event.py`
+
+### Cache Usage Patterns
+```python
+# User cache example
+user = User(phone_number="1234567890", user_name="John")
+await self.user_cache.set("user_profile:1234567890", user, ttl=3600)
+cached_user = await self.user_cache.get("user_profile:1234567890", models=User)
+
+# Table cache example  
+message_log = MessageLog(user_id="1234567890")
+await self.table_cache.set("msg_history:1234567890", message_log)
+
+# State cache example
+state = StateHandler()
+state.activate_wappa()
+await self.state_cache.set("wappa_state:1234567890", state, ttl=1800)
+```
+
+## Monitoring
+
+### Cache Statistics
+Use `/STATS` command to monitor:
+- File system connectivity
+- Total operations count
+- Cache hit/miss ratios
+- Error rates and health status
+
+### Logging
+Comprehensive logging with structured output:
+- User operations (cache hits/misses)
+- Message processing (success/failure)  
+- Command handling (state changes)
+- Cache statistics (performance metrics)
+
+## Comparison with Redis
+
+| Feature | JSON Cache | Redis Cache |
+|---------|------------|-------------|
+| **Setup** | No dependencies | Requires Redis server |
+| **Persistence** | Always persistent | Configurable |  
+| **Performance** | Good (file I/O) | Excellent (memory) |
+| **Scalability** | Moderate | High |
+| **Reliability** | High (no external deps) | High (with proper setup) |
+| **Development** | Simple | Requires Redis knowledge |
+
+## Use Cases
+
+**JSON Cache is ideal for**:
+- Development and testing environments
+- Small to medium WhatsApp bots (< 1000 active users)
+- Applications requiring guaranteed persistence
+- Deployments without external dependencies
+- Scenarios where setup simplicity is important
+
+**Consider Redis for**:
+- High-traffic applications (> 1000 concurrent users)
+- Applications requiring sub-millisecond cache responses
+- Distributed deployments
+- Advanced Redis features (pub/sub, streams, etc.)

wappa-0.1.8/wappa/cli/examples/openai_transcript/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

wappa-0.1.8/wappa/cli/examples/redis_cache_example/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa-0.1.8/wappa/cli/examples/simple_echo_example/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa-0.1.8/wappa/cli/examples/simple_echo_example/.python-version

@@ -0,0 +1 @@
+3.12

wappa-0.1.8/wappa/cli/examples/simple_echo_example/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "simple-echo-example"
+version = "0.1.0"
+description = "Simple WhatsApp echo bot example using Wappa framework"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "wappa>=0.1.6",
+]