Proposal: Expand FlowisePy SDK to full API coverage + new modular structure

[aritzjl]

Summary

FlowisePy currently covers only a few endpoints while the official Flowise REST API includes 13 endpoint groups. I would like to contribute a significant but incremental upgrade that:

• Implements 100% of the official endpoint groups
• Refactors the SDK into a scalable modular architecture
• Adds typed models for every resource
• Introduces a robust exception hierarchy
• Preserves backward compatibility where possible

This Issue is an RFC before beginning PRs.

---

Official API Blocks to be Implemented (full coverage)

Based on the Flowise documentation, the SDK will cover all of:

1. Assistants
2. Attachments
3. Chat Message
4. Chatflows
5. Document Store
6. Feedback
7. Leads
8. Ping
9. Prediction
10. Tools
11. Upsert History
12. Variables
13. Vector Upsert

Each of these will receive a dedicated model and resource module.

---

Proposed SDK Architecture

flowise/
    client.py

    utils/
        http.py
        types.py

    exceptions/
        __init__.py
        common.py
        http.py
        auth.py
        api.py
        validation.py
        parsing.py

    models/
        assistants.py
        attachments.py
        chat_message.py
        chatflows.py
        document_store.py
        feedback.py
        leads.py
        ping.py
        prediction.py
        tools.py
        upsert_history.py
        variables.py
        vector_upsert.py

    resources/
        assistants.py
        attachments.py
        chat_message.py
        chatflows.py
        document_store.py
        feedback.py
        leads.py
        ping.py
        prediction.py
        tools.py
        upsert_history.py
        variables.py
        vector_upsert.py

Benefits

• Mirrors Flowise API structure exactly
• Easy to extend when new endpoints are added
• Better user experience (flowise.chatflows.predict(...))
• Fully typed models
• Cleaner error handling

---

Contribution Plan (multiple small PRs)

To keep the project reviewable:

PR 1 — Structural foundation

• Create folders: models/, resources/, exceptions/, utils/
• Add base classes (BaseModel, BaseResource)
• Add full exception hierarchy
• Move current client code without breaking behavior

PR 2 — Prediction endpoints

PR 3 — Chatflows endpoints

PR 4 — Assistants endpoints

PR 5 — Attachments endpoints

PR 6 — Chat Message endpoints

PR 7 — Document Store

PR 8 — Feedback

PR 9 — Leads

PR 10 — Tools

PR 11 — Upsert History

PR 12 — Variables

PR 13 — Vector Upsert

PR 14 — Tests + updated examples

Each PR will be small and focused.

---

Questions for maintainers

Before beginning:

1. Do you approve a redesign for full coverage of these 13 official API blocks?
2. Is the proposed modular architecture acceptable?
3. Should PRs follow the plan above (one block per PR)?
4. Any style preferences or constraints to follow?

---

Closing

This redesign would bring FlowisePy to full API parity, make it much easier to maintain, and significantly improve the Python developer experience.
Happy to adjust anything based on your feedback.

Thanks!

---