Metadata-Version: 2.4
Name: llama-index-readers-feishu
Version: 0.1.0
Summary: LlamaIndex data loaders for Feishu/Lark wiki, docs, and drive
Project-URL: Homepage, https://github.com/jinzcdev/llama-index-readers-feishu
Project-URL: Repository, https://github.com/jinzcdev/llama-index-readers-feishu
Project-URL: Documentation, https://github.com/jinzcdev/llama-index-readers-feishu#readme
Project-URL: Bug Tracker, https://github.com/jinzcdev/llama-index-readers-feishu/issues
Project-URL: Changelog, https://github.com/jinzcdev/llama-index-readers-feishu/blob/main/CHANGELOG.md
Author-email: Zhichao Jin <jinzcdev@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: LLM,NLP,RAG,feishu,index,lark,llamaindex,retrieval
Requires-Python: <4.0,>=3.10
Requires-Dist: lark-oapi<2,>=1.4.0
Requires-Dist: llama-index-core<0.15,>=0.12.0
Description-Content-Type: text/markdown

# LlamaIndex Feishu Readers

[![PyPI version](https://img.shields.io/pypi/v/llama-index-readers-feishu)](https://pypi.org/project/llama-index-readers-feishu/)
[![Python versions](https://img.shields.io/pypi/pyversions/llama-index-readers-feishu)](https://pypi.org/project/llama-index-readers-feishu/)
[![License: MIT](https://img.shields.io/pypi/l/llama-index-readers-feishu)](https://github.com/jinzcdev/llama-index-readers-feishu/blob/main/LICENSE)
[![CI](https://github.com/jinzcdev/llama-index-readers-feishu/actions/workflows/ci.yml/badge.svg)](https://github.com/jinzcdev/llama-index-readers-feishu/actions/workflows/ci.yml)
[![Downloads](https://static.pepy.tech/badge/llama-index-readers-feishu)](https://pepy.tech/project/llama-index-readers-feishu)
[![中文文档](https://img.shields.io/badge/docs-中文-blue)](README.zh-CN.md)

Load documents from Feishu/Lark into [LlamaIndex](https://github.com/run-llama/llama_index). This package provides three readers backed by the official [`lark-oapi`](https://github.com/larksuite/oapi-sdk-python) SDK:

- **FeishuWikiReader** — load documents from wiki spaces (with recursive subnode support)
- **FeishuDocsReader** — load individual docx documents by token
- **FeishuDriveReader** — load docx documents from cloud drive folders (with recursive subfolder support)

> [!NOTE]
> The official `llama-index-readers-feishu-wiki` package has been removed from LlamaIndex, and `llama-index-readers-feishu-docs` is no longer maintained. This project carries the work forward with expanded Feishu document loading for wiki, docs, and drive.

## Installation

```bash
pip install llama-index-readers-feishu
```

## Prerequisites

1. Create a Feishu custom app in the [developer console](https://open.feishu.cn/app/).
2. Enable permissions based on the reader you use:

| Reader | Required scopes                                                            |
| ------ | -------------------------------------------------------------------------- |
| Wiki   | `wiki:wiki:readonly` or `wiki:node:retrieve`, `docs:document.content:read` |
| Docs   | `docs:document.content:read` or `docx:document:readonly`                   |
| Drive  | `drive:drive:readonly` or `drive:drive`, `docs:document.content:read`      |

3. Grant the app access to the target wiki space or drive folder.

## Quick Start

### Wiki

```python
from llama_index.readers.feishu import FeishuWikiReader

reader = FeishuWikiReader(app_id="cli_xxx", app_secret="your_app_secret")
documents = reader.load_data(
    space_id="your_space_id",
    parent_node_token="optional_parent_node_token",
    recursive=True,
)
```

### Docs

```python
from llama_index.readers.feishu import FeishuDocsReader

reader = FeishuDocsReader(app_id="cli_xxx", app_secret="your_app_secret")
documents = reader.load_data(document_ids=["docx_token_1", "docx_token_2"])
```

### Drive

```python
from llama_index.readers.feishu import FeishuDriveReader

reader = FeishuDriveReader(app_id="cli_xxx", app_secret="your_app_secret")
documents = reader.load_data(
    folder_token="your_folder_token",
    recursive=True,
)
```

The drive reader loads:

- Files with `type=docx`
- Shortcuts where `shortcut_info.target_type=docx`

Other file types (folders, sheets, bitables, etc.) are skipped. Folders are traversed when `recursive=True`.

## Post-process Exported Text

Feishu markdown exports may embed HTML fragments such as tables. Pass plugins to normalize loaded text:

```python
from llama_index.readers.feishu import (
    FeishuDriveReader,
    RegexPlugin,
    html_table_to_markdown_plugin,
)

reader = FeishuDriveReader(
    app_id="cli_xxx",
    app_secret="your_app_secret",
    plugins=[
        html_table_to_markdown_plugin,
        RegexPlugin(pattern=r"\n{3,}", repl="\n\n", name="collapse_blank_lines"),
    ],
)
documents = reader.load_data(folder_token="your_folder_token")
```

Use `default_markdown_plugins()` for the built-in HTML table converter and Feishu markdown unescape plugin.

## User Access Token

To access content with user identity instead of tenant identity:

```python
reader = FeishuWikiReader(
    app_id="cli_xxx",
    app_secret="your_app_secret",
    user_access_token="u-xxxxxxxx",
)
```

## Lark (Overseas)

```python
reader = FeishuWikiReader(
    app_id="cli_xxx",
    app_secret="your_app_secret",
    domain="https://open.larksuite.com",
)
```

Or switch after initialization:

```python
reader = FeishuWikiReader(app_id="cli_xxx", app_secret="your_app_secret")
reader.set_lark_domain()
```

## Use with LlamaIndex

```python
from llama_index.core import VectorStoreIndex

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("Summarize the content")
print(response)
```

## Examples

Integration scripts under `examples/` load live content and export markdown files. Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
# edit .env with your Feishu app credentials and target IDs

# Wiki
python examples/load_wiki_documents.py

# Docs
python examples/load_docs_documents.py

# Drive
python examples/load_drive_documents.py
```

## Development

```bash
uv sync
uv run poe hooks-install
uv run poe lint
uv run poe test
uv run poe test-cov        # optional: with coverage report
```

## License

MIT
