Metadata-Version: 2.4
Name: zafiro-skill-whatsapp
Version: 0.1.1
Summary: WhatsApp skill package extracted from ia_orchestrator core
Author-email: Gerald Padilla <gpadillaq@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Zafiro-IA/whatsapp-skill
Project-URL: Repository, https://github.com/Zafiro-IA/whatsapp-skill
Project-URL: Issues, https://github.com/Zafiro-IA/whatsapp-skill/issues
Keywords: whatsapp,skill,orchestrator,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.31
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: python-magic>=0.4.27
Requires-Dist: neonize
Dynamic: license-file

# zafiro-skill-whatsapp

Autonomous WhatsApp skill package for the Zafiro orchestrator ecosystem.

This package is designed to run as an external skill pack with no direct imports from core `app.*` modules or other skill packages.

## Documentation map

- Core integration guide: `docs/CORE_INTEGRATION.md`
- Full tools contract: `docs/TOOLS_REFERENCE.md`
- Skill manifest/prompt: `skills/whatsapp.md`

## What this package contains

- Skill manifest: `skills/whatsapp.md`
- Skill entry-point registrar: `zafiro_skill_whatsapp.extensions.skills.whatsapp:register_whatsapp_skill`
- Tool entry-point registrar: `zafiro_skill_whatsapp.extensions.tools.whatsapp_tools:register_whatsapp_tools`
- WhatsApp adapter split by domain (`runtime_ops`, `message_ops`, `contacts_ops`, `sync_ops`)
- Policy tools (outbound allowlist and inbound auto-reply controls)
- CLI helpers for `/wa`-style commands
- Local integration layer (`zafiro_skill_whatsapp.integrations`) with optional host hooks

## Adapter layout

```
adapters/whatsapp/
├── __init__.py               # public facade + centralized legacy module aliases
├── __main__.py               # package launcher entrypoint
├── runtime_ops/              # runtime lifecycle/state/config/types
├── message_ops/              # inbound/outbound/processing/auto-reply/queue
├── contacts_ops/             # directory/discovery/policy
└── sync_ops/                 # history/contacts/all-sync orchestration
```

Backward compatibility: legacy imports like `adapters.whatsapp.contacts`,
`adapters.whatsapp.outbound`, `adapters.whatsapp.state`, etc. are exposed by
central alias registration in `adapters/whatsapp/__init__.py`.

Runtime note:

- The old flat runtime modules (`config`, `state`, `connection`, `types`) were moved
	to `runtime_ops/`.
- Legacy import paths remain available through centralized aliasing in
	`adapters/whatsapp/__init__.py`.

## Local-only artifacts

Keep local execution artifacts out of git (logs, data, media, plan exports).
For plan files generated during local experimentation, use:

- `local_runtime/plans_created/`

This package `.gitignore` excludes these folders by default:

- `logs/`
- `data/`
- `media/`
- `local_runtime/`
- `plans_created/`

## Install

From repository root:

```bash
./venv/bin/python -m pip install -e packages/whatsapp_skill
```

## Console Testing Script

There is now a standalone console tester for this package:

Quick shortcut from repo root (recommended):

```bash
./packages/whatsapp_skill/scripts/wa.sh tools
./packages/whatsapp_skill/scripts/wa.sh tool wa_policy
./packages/whatsapp_skill/scripts/wa.sh tool save_whatsapp_contact "Gerald|50577427779|true|owner"
./packages/whatsapp_skill/scripts/wa.sh wa "status"
./packages/whatsapp_skill/scripts/wa.sh wa "sync"
./packages/whatsapp_skill/scripts/wa.sh wa "sync Zafiro"
./packages/whatsapp_skill/scripts/wa.sh wa "sync Zafiro 50 12 8"
./packages/whatsapp_skill/scripts/wa.sh repl
```

Direct python entrypoint (equivalent):

```bash
python packages/whatsapp_skill/scripts/wa_console.py list-tools
python packages/whatsapp_skill/scripts/wa_console.py run-tool wa_policy
python packages/whatsapp_skill/scripts/wa_console.py run-tool save_whatsapp_contact "Gerald|50577427779|true|owner"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "status"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "sync"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "sync Zafiro"
python packages/whatsapp_skill/scripts/wa_console.py run-wa "sync Zafiro 50 12 8"
python packages/whatsapp_skill/scripts/wa_console.py repl
```

What it covers:

- `run-tool`: Executes any registered WhatsApp tool from this skill package.
- `run-wa`: Executes `/wa` admin subcommands (`on`, `off`, `status`, `link`, `unlink`, `actor`, etc.).
- `repl`: Interactive shell where you can test tool/admin commands quickly.

`/wa sync` UX (recommended):

- `/wa sync`: global adaptive sync validation.
- `/wa sync <target> [limit] [max_rounds] [wait_seconds]`: one-shot target sync + archive read.
- Compatibility aliases still available: `sync auto`, `sync oneshot`, `sync os`, `sync all`.

## Skill and tools

Skill name: `WhatsApp`

Declared tools:

- `save_whatsapp_contact`
- `save_whatsapp_contacts`
- `list_whatsapp_contacts`
- `save_whatsapp_group`
- `save_whatsapp_groups`
- `list_whatsapp_groups`
- `send_whatsapp`
- `read_whatsapp`
- `read_whatsapp_archive`
- `reply_whatsapp`
- `whatsapp_status`
- `whatsapp_recover`
- `wa_sync_auto`
- `get_group_recent_messages`
- `wa_policy`
- `wa_set_autoreply` (legacy compatibility)
- `wa_allow_send`
- `wa_block_send`
- `wa_allow_reply`
- `wa_block_reply`
- `list_whatsapp_tools`

See `docs/TOOLS_REFERENCE.md` for exact argument formats, examples, and output semantics for each tool.

## Runtime model

- Standalone defaults live in `zafiro_skill_whatsapp.integrations`.
- Archive/history, contacts, groups and access-rules use ORM-backed tables created by this skill.
- Data is scoped by connected WhatsApp number (multi-account safe).
- If host ORM is configured (`orm_session_factory` or `orm_engine_factory`), tables are created/reused there.
- If host ORM is not configured, the skill logs a warning and falls back to local SQLite at `WHATSAPP_LOCAL_DB_PATH`.
- Optional host runtime hooks can be provided with `configure_host_runtime(...)` to bridge:
	- active-agent listing
	- task execution
	- effective-agent resolution
	- host ORM session/engine and storage account resolver

See `docs/CORE_INTEGRATION.md` for a full bootstrap example and deployment checklist.

## Host integration contract

- Contract metadata API: `get_host_runtime_contract()`.
- Contract validation API: `validate_host_runtime_contract(...)`.
- Fail-fast API: `assert_host_runtime_contract(...)`.

Expected hooks by mode:

- Core shared database mode (recommended):
	- required: `orm_session_factory` or `orm_engine_factory`
- Multi-account strict mode (recommended):
	- required: `resolve_storage_account_key`
- Optional:
	- `storage_schema_initializer`
	- `get_active_agents`, `execute_task`, `resolve_effective_agent`

Bootstrap order (recommended):

1. `configure_host_runtime(...)`
2. `assert_host_runtime_contract(...)`
3. Load entry points and register skills/tools

Dependency contract:

- Python dependencies are installed by package manager when this skill is added:
	- `sqlalchemy`, `python-magic`, `neonize`
- System dependency required by runtime:
	- `libmagic` (OS package; must be present on host image)

## Entry points

`pyproject.toml` exports:

- `zafiro.skills` -> `whatsapp`
- `zafiro.tools` -> `whatsapp`

## Key environment variables

- `WHATSAPP_SESSION_NAME`
- `WHATSAPP_DEVICE_PLATFORM`
- `WHATSAPP_DEVICE_OS`
- `WHATSAPP_DEVICE_VERSION`
- `WHATSAPP_OUTBOX_DIR`
- `WHATSAPP_CONTACTS_PATH`
- `WHATSAPP_ACCESS_RULES_PATH`
- `WHATSAPP_MEDIA_DIR`
- `WHATSAPP_ACTIVE_ACCOUNT_PATH`
- `MESSAGE_ARCHIVE_PATH`
- `WHATSAPP_LOCAL_DB_PATH`
- `RECENT_SESSION_HISTORY_LIMIT`
- `WHATSAPP_FORWARD_URL`
- `WHATSAPP_FORWARD_SECRET`
- `WHATSAPP_SIMULATE_TYPING`
- `WHATSAPP_TYPING_MIN_MS`
- `WHATSAPP_TYPING_MAX_MS`
- `WHATSAPP_TYPING_MS_PER_CHAR`
- `WHATSAPP_SEND_AVAILABLE_PRESENCE`
- `WHATSAPP_AUTO_MARK_READ`
- `WHATSAPP_AUTO_REPLY_ENABLED`

## Validation checklist (current)

- No AST-level imports from `app`, `zafiro_skill_hostal`, or `zafiro_skill_media`
- Package imports succeed:
	- `zafiro_skill_whatsapp`
	- `zafiro_skill_whatsapp.integrations`
	- `zafiro_skill_whatsapp.extensions.tools.whatsapp_tools`
	- `zafiro_skill_whatsapp.extensions.skills.whatsapp`
