Metadata-Version: 2.4
Name: markanm
Version: 0.1.0a3
Summary: Official Python SDK for MarkanM Chat Bot Platform & REST API (v0.1.0-alpha)
Author-email: MarkanM Developer Team <developers@markanm.com>
License: MIT License
        
        Copyright (c) 2026 MarkanM Developer Team
        
        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.
        
Project-URL: Homepage, https://chat.markanm.com/developers
Project-URL: Documentation, https://chat.markanm.com/developers/docs
Project-URL: Repository, https://github.com/markanm/markanm-python-sdk
Keywords: markanm,bot,chat,sdk,api,oauth,webhooks
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Dynamic: license-file
Dynamic: requires-python

# MarkanM Python SDK

Python SDK for the MarkanM bot API: bot identity, room messages, command/event dispatch, polling, signed webhooks, and an OpenAI-compatible AI helper. The server currently exposes `GET /me`, `POST /rooms/{roomId}/messages`, and `POST /polling` under `/api/bot/v1`; methods for other platform features are not advertised until the backend supports them.

## Requirements and install

- Python 3.9 or newer (the SDK uses `asyncio.to_thread`).
- `httpx` is installed with the package; it provides async HTTP and TLS handling.

```bash
python -m pip install markanm
```

On Kali Linux and other Debian based distributions, system Python may be externally managed (PEP 668). Do not use `sudo pip` or force `--break-system-packages`. Create a virtual environment:

```bash
sudo apt update
sudo apt install python3-venv python3-pip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install markanm
```

If `venv` reports that `ensurepip` is unavailable, install the matching `python3-venv` package for your Kali Python version, then recreate the environment. Activate `.venv` in each new shell before running the bot. Use the system package manager for OS packages; avoid `sudo pip`.

## Quick start: polling bot

Create a bot and copy its token from the MarkanM developer portal. Keep the token in an environment variable:

```bash
export MARKANM_BOT_TOKEN="mkbot_..."
```

```python
import os
from markanm import Bot

bot = Bot(os.environ["MARKANM_BOT_TOKEN"])

@bot.command("hello")
async def hello(ctx):
    await ctx.reply(f"Hello, {ctx.user.display_name or 'there'}!")

@bot.on("command.received")
async def log_command(event):
    print(event.id, event.type)

bot.run_polling(interval=2.0)
```

Run `python bot.py`. Polling is intended for local development and simple deployments. Since the server marks fetched events as delivered before your handlers finish, keep handlers fast and make side effects safe to repeat. For hosted production bots, configure a webhook.

## API methods

```python
profile = await bot.get_me()
result = await bot.send_message(room_id="123", text="Hi")
await bot.poll_once()  # fetch one batch and dispatch it
bot.stop()             # request run_polling() to stop
```

`send_message` accepts an optional `card` dictionary. The current backend stores card content as a formatted text message; it does not yet expose interactive button callbacks. `CommandContext` provides `command`, `text`, `args`, `user`, `room`, `room_id`, `message`, and `await ctx.reply(text)`.

`@bot.on("event.type")` registers event listeners. Handlers may be synchronous or `async def`. Handler errors are logged and do not stop polling. `Event` exposes `id`, `type`, `timestamp`, `payload`, and `raw_data`.

## Webhooks

The webhook signature is `X-MarkanM-Signature: t=UNIX_SECONDS,v1=HEX_HMAC_SHA256`, computed over `timestamp + "." + exact_raw_body` with the bot webhook secret. Preserve the raw request bytes before JSON parsing and pass the exact body to the SDK:

```python
event = await bot.handle_webhook(raw_body, request.headers["X-MarkanM-Signature"])
```

The default accepted timestamp drift is five minutes. Webhook event formats follow the same `Event` model as polling.

## AI helper

The `AI` helper supports OpenAI, Groq, Mistral, DeepSeek, Together, Perplexity, Sarvam, Anthropic, Gemini, Cohere, Hugging Face, Ollama, OpenRouter, and custom OpenAI-compatible endpoints:

```python
from markanm import AI

ai = AI(provider="openai", api_key=os.environ["OPENAI_API_KEY"], model="gpt-4o-mini")
answer = await ai.chat("Suggest a greeting")  # keeps in-memory conversation history
ai.reset()
```

AI calls use your provider credentials directly and are billed by that provider. Do not put provider keys in client side code.

## Errors and network troubleshooting

All SDK exceptions derive from `MarkanMError`. API errors include `status_code`, `error_code`, and optional `request_id`; rate limit errors also expose `retry_after`. TLS certificate verification remains enabled. On Kali, install/update the OS CA bundle (`sudo apt install ca-certificates && sudo update-ca-certificates`) instead of disabling certificate checks. Check system time, DNS, outbound HTTPS access, token validity, API base URL, and that the bot is active. For a self-hosted endpoint, pass `base_url="https://host.example/api/bot/v1"`.

```python
from markanm import MarkanMAPIError, MarkanMRateLimitError

try:
    await bot.send_message("123", "Hello")
except MarkanMRateLimitError as exc:
    print("Retry after", exc.retry_after)
except MarkanMAPIError as exc:
    print(exc.status_code, exc.error_code, exc.request_id)
```

## Publishing

From this directory, build with `python -m build`, inspect the wheel and sdist in `dist/`, then upload with `python -m twine upload dist/*`. Use a PyPI token or trusted publishing in CI; do not commit credentials. Version numbers must be unique on PyPI.

## License

MIT. See [LICENSE](LICENSE).
