Metadata-Version: 2.4
Name: concinno-skills-support
Version: 0.1.0
Summary: Customer support agent skills (Zendesk + Intercom) for Concinno — Databricks 2026 #1 enterprise landing use case.
Project-URL: Homepage, https://github.com/aiking931931/concinno
Project-URL: Issues, https://github.com/aiking931931/concinno/issues
Project-URL: Changelog, https://github.com/aiking931931/concinno/blob/main/projects/concinno-skills-support/CHANGELOG.md
Author-email: "AI King (Chen-Xuan Wang)" <me@ai-king.dev>
License-Expression: Apache-2.0
Keywords: agent,concinno,customer-service,helpdesk,intercom,skills,support,ticket,zendesk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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 :: Office/Business :: Groupware
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: concinno>=2.15.1
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# concinno-skills-support

Customer-support agent skills for [Concinno](https://pypi.org/project/concinno/).
Targets the **Databricks 2026 #1 enterprise landing use case**
(customer service: finance 23% / retail 27%). Native Python REST wrappers,
**Apache-2.0 / MIT SDKs only** — we deliberately avoid `zenpy` (GPL-3.0)
to keep the Concinno ecosystem copy-left-free.

## Status

MVP (0.1.0) — three one-shot tools:

| Tool class        | Platform | Underlying transport | Licence      |
|-------------------|----------|----------------------|--------------|
| `ZendeskTicket`   | Zendesk  | `httpx` (REST v2)    | Apache-2.0   |
| `ZendeskSearch`   | Zendesk  | `httpx` (REST v2)    | Apache-2.0   |
| `IntercomMessage` | Intercom | `httpx` (REST)       | Apache-2.0   |

Both platforms are reached via Concinno's existing `httpx` main dependency;
this package therefore adds **zero** additional runtime dependencies
beyond Concinno itself.

## Install

```bash
pip install concinno-skills-support
```

## Credentials

Each platform's credentials live under well-known keys in the Concinno
`CredentialStore`, which reads (in order):

1. Process runtime overrides via `CredentialStore.set(...)`.
2. Env var `CONCINNO_CRED_<UPPER_KEY>`.
3. `~/.concinno/credentials.json`.

### Zendesk

Two supported auth shapes (OAuth is tried first):

| Key                      | Env var                                   |
|--------------------------|-------------------------------------------|
| `zendesk_subdomain`      | `CONCINNO_CRED_ZENDESK_SUBDOMAIN`         |
| `zendesk_email`          | `CONCINNO_CRED_ZENDESK_EMAIL`             |
| `zendesk_api_token`      | `CONCINNO_CRED_ZENDESK_API_TOKEN`         |
| `zendesk_oauth_token`    | `CONCINNO_CRED_ZENDESK_OAUTH_TOKEN`       |

API-token auth uses the official `{email}/token:{api_token}` Basic-auth
format documented by Zendesk.

### Intercom

| Key                      | Env var                                   |
|--------------------------|-------------------------------------------|
| `intercom_access_token`  | `CONCINNO_CRED_INTERCOM_ACCESS_TOKEN`     |

Example `~/.concinno/credentials.json`:

```jsonc
{
  "zendesk_subdomain": "acme",
  "zendesk_email": "agent@acme.com",
  "zendesk_api_token": "…",
  "intercom_access_token": "dG9rZW4="
}
```

If a token is missing the tool returns
`{"error": "no <service> credentials — set via CredentialStore / env"}`
rather than crashing.

## Usage via Concinno `ToolRegistry`

When the consumer sets `CONCINNO_LOAD_PLUGINS=1`, the default registry
auto-mounts every support tool:

```python
import os
os.environ["CONCINNO_LOAD_PLUGINS"] = "1"

from concinno.tools.registry import get_default_registry

reg = get_default_registry()
assert {"ZendeskTicket", "ZendeskSearch", "IntercomMessage"} <= set(
    reg.list_deferred()
)

ticket = reg.get("ZendeskTicket")
ticket.call(action="list", status="open", limit=20)
```

## Direct Python usage

```python
from concinno_skills_support import (
    ZendeskTicket,
    ZendeskSearch,
    IntercomMessage,
)

ZendeskTicket().call(action="list", status="open", limit=50)
ZendeskTicket().call(
    action="create",
    subject="Login broken",
    comment="Customer reports 401 on sign-in",
    requester_email="user@example.com",
    priority="urgent",
)
ZendeskSearch().call(
    action="search", query="status:open priority:urgent", limit=25
)
IntercomMessage().call(
    action="send",
    conversation_id="conv-42",
    body="We're on it — thanks for flagging.",
    admin_id="admin-7",
)
```

All tools return `{"ok": True, ...}` or a structured payload on success,
or `{"error": "..."}` on failure — same shape as the other Concinno
built-in tools. No exceptions escape the `call()` surface.

## Concurrency

All three tools set `is_concurrency_safe = False`. Both Zendesk and
Intercom enforce tenant-scoped rate limits, and ticket/conversation
mutation is order-sensitive. The Concinno scheduler will honour this
automatically.

## Safety caps

- Zendesk search `query` ≤ **500** chars.
- Zendesk ticket `comment` body ≤ **50 000** chars.
- Intercom `body` ≤ **10 000** chars.

## License

Apache-2.0. See `LICENSE` in the Concinno monorepo.
