hermes-lark-oapi-mini 0.1.0

Unofficial minimal Feishu/Lark OpenAPI client surface used by Hermes Agent

Hermes Lark OAPI Mini

hermes-lark-oapi-mini is an unofficial, minimal Feishu/Lark OpenAPI client surface created for 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

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

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

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