Metadata-Version: 2.4
Name: hermes-lark-oapi-mini
Version: 0.1.0
Summary: Unofficial minimal Feishu/Lark OpenAPI client surface used by Hermes Agent
Author: andersguo
License-Expression: MIT
Project-URL: Homepage, https://github.com/guoxiaod/hermes-lark-oapi-mini
Project-URL: Repository, https://github.com/guoxiaod/hermes-lark-oapi-mini
Project-URL: Issues, https://github.com/guoxiaod/hermes-lark-oapi-mini/issues
Keywords: feishu,lark,openapi,hermes-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets<16,>=15.0.1
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Hermes Lark OAPI Mini

`hermes-lark-oapi-mini` is an unofficial, minimal Feishu/Lark OpenAPI client surface created for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

It exists to reduce Hermes gateway startup and idle memory usage when the Feishu channel is enabled. It intentionally implements only the subset of the official `lark-oapi` Python SDK that Hermes currently calls.

## Important Notice

This package is **not official** and is **not affiliated with Feishu, Lark, or ByteDance**.

This package is **not a complete Feishu/Lark SDK** and is **not a drop-in replacement** for the official `lark-oapi` package. If you are building a general Feishu/Lark application, use the official SDK unless you have verified that this mini client covers your exact API surface.

## Package Names

- PyPI distribution: `hermes-lark-oapi-mini`
- Python import: `lark_oapi_mini`

The PyPI name intentionally includes `hermes` to make the scope clear and reduce confusion with official Feishu/Lark packages.

## Installation

```bash
pip install hermes-lark-oapi-mini
```

## Supported Surface

The supported API surface is limited to what Hermes Agent uses today:

- `Client.builder()` and `client.request(BaseRequest)`
- `AccessTokenType`, `HttpMethod`, and `BaseRequest.builder()`
- IM message create, reply, update, and get request builders
- IM image and file upload request builders
- IM message resource download request builder
- IM message reaction create and delete request builders
- Application get request builder
- Contact user get request builder
- Event dispatcher builder for Hermes Feishu events
- Card callback response builders
- WebSocket endpoint discovery through `/callback/ws/endpoint`
- Minimal WebSocket event frame parse/ACK behavior used by Hermes

Anything not listed here should be treated as unsupported.

## Example

```python
import json

import lark_oapi_mini as lark
from lark_oapi_mini.api.im.v1 import CreateMessageRequest, CreateMessageRequestBody

client = (
    lark.Client.builder()
    .app_id("cli_xxx")
    .app_secret("secret")
    .build()
)

body = (
    CreateMessageRequestBody.builder()
    .receive_id("oc_xxx")
    .msg_type("text")
    .content(json.dumps({"text": "hello"}))
    .uuid("example-uuid")
    .build()
)

request = (
    CreateMessageRequest.builder()
    .receive_id_type("chat_id")
    .request_body(body)
    .build()
)

response = client.im.v1.message.create(request)
print(response.success(), response.code, response.msg)
```

## Why This Exists

Hermes Agent can run many long-lived gateway processes. The official `lark-oapi` package imports a large generated SDK surface even when Hermes only uses a small part of it. In deployments with many Feishu-enabled Hermes gateways, that eager import cost can become a meaningful steady-state memory cost.

This package keeps the runtime surface small by implementing only the request/response models and transport behavior Hermes needs.

## Non-Goals

- No attempt to cover the full Feishu/Lark OpenAPI.
- No compatibility guarantee for APIs Hermes does not use.
- No generated model coverage.
- No promise to match every behavior of the official SDK.
- No official support from Feishu/Lark.

## Compatibility

The package targets Python 3.11+.

The public API may change while the package is in `0.x` versions. Compatibility is primarily measured against Hermes Agent's Feishu channel tests.

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check dist/*
```

## 中文说明

这是一个非官方的 Feishu/Lark OpenAPI 最小客户端，主要服务于 Hermes Agent 的飞书 channel，用来降低官方 `lark-oapi` SDK 带来的启动和空闲内存开销。

它不是完整 SDK，也不是官方包，不建议作为通用飞书应用开发客户端使用。除 Hermes 当前用到的接口外，其他能力都应视为不支持。

## License

MIT
