feat: Add Frappe CRM, Helpdesk, Raven, and ERPNext agent integration tools#277
Merged
Merged
Conversation
Adds three new internal Frappe app tool modules with full CRUD and business-automation coverage: - huf/ai/tools/crm.py: 10 tools for Frappe CRM — lead/deal lifecycle (get, create, update), notes, tasks, and contact lookup - huf/ai/tools/helpdesk.py: 8 tools for Frappe Helpdesk — ticket management, comments, agent/team listing, and assignment - huf/ai/tools/raven.py: 6 tools for Frappe Raven — send/search messages, list/create channels, channel membership All tools use direct Frappe API calls (no httpx/credentials) and guard against the app not being installed. Registry and install seeding updated.
Adds 5 new tool modules covering broad ERPNext business automation: erpnext.py (14 tools — ERPNext Tools category): Sales/Purchase Invoices, Payment Entry, Quotation, Customer CRUD, Account Ledger (GL queries), Journal Entry creation, RFQ listing erpnext_crm.py (7 tools — ERPNext CRM Tools category): ERPNext-native CRM: Lead and Opportunity lifecycle (get/create/update). Differentiated from standalone Frappe CRM (CRM Lead / CRM Deal) by doctype names, tool prefix (erpnext_crm_*), and category label. erpnext_inventory.py (12 tools — ERPNext Inventory category): Item/Item Price lookup, BOM get/create, real-time Stock Balance (SLE dedup), Stock Movements, Stock Entries, Warehouses, Delivery Notes, Purchase Receipts erpnext_reports.py (14 tools — ERPNext Reports category): Balance Sheet, P&L, Trial Balance, General Ledger, Accounts Receivable/Payable, Bank Reconciliation, Sales Register, Sales Order Analysis, Customer Acquisition, Stock Balance, Stock Ledger, Item-wise Sales, Gross Profit All via frappe.desk.query_report.run — read-only, no side effects. Registry updated to 89 tools across 9 categories. Frappe CRM tools renamed category to "Frappe CRM Tools" to distinguish from ERPNext CRM. All files AST-validated clean.
Three new documentation files covering the full memory architecture: - docs/SCOPED_MEMORY_KNOWLEDGE_BRIDGE_RFC.md — Updated RFC reflecting current state: three live backends (sqlite_fts, sqlite_vec, chroma), Phase 1 implemented via PR #275, phases 2–5 defined with learning profiles and learning agents - docs/memory/zero-to-hero.md — Full onboarding doc capturing intellectual provenance (Agno/Hindsight/Mem0 references), how existing knowledge backends work, the three-layer architecture, what exists today vs what is planned, key files, design decisions and their reasons, glossary - docs/memory/phase-plan.md — Per-phase delivery plan with definition of done, file-level targets, cross-cutting concerns (security, testing, backward compat)
…pdated RFC" This reverts commit a2f6ac7.
Replaces one-tool-per-operation pattern with an action-dispatcher pattern. Each tool file exposes a single handle_action(**kwargs) that routes via an 'action' kwarg. Internal logic is unchanged — only renamed to _handle_*. Tool count: 89 → 13 slack (6 actions: send_message, reply_thread, list_channels, ...) discord (4 actions: send_message, get_messages, list_channels, ...) telegram (1 action: send_message) github (6 actions: list_repos, get_repo, create_issue, ...) get_recipient (utility, unchanged) frappe_crm (11 actions: leads + deals + notes + tasks + contacts) helpdesk (8 actions: tickets + comments + agents + teams) raven (6 actions: messages + channels + members) erpnext (14 actions: invoices + payments + customers + ledger + ...) erpnext_crm (7 actions: leads + opportunities) erpnext_inventory (12 actions: items + BOM + stock + warehouses + ...) erpnext_run_report — run any ERPNext report by name + filters dict erpnext_list_reports — discover ~90 reports across 9 modules erpnext_reports.py replaced with a REPORT_CATALOGUE covering 90+ reports across Accounts, Selling, Buying, Stock, Manufacturing, CRM, Helpdesk, Projects and HR — all accessible via two generic tools instead of 14+ individual ones.
…s only Slack, Discord, Telegram, GitHub and recipient tools were already merged to develop (PR #273) and should not be refactored in this branch. Reverted to develop-identical state: huf/ai/tools/slack.py huf/ai/tools/discord.py huf/ai/tools/telegram.py huf/ai/tools/github.py huf/ai/tools/recipient.py Registry now has 26 tools: 18 from develop (unchanged) — individual slack_*/discord_*/github_* tools 8 new (consolidated) — frappe_crm, helpdesk, raven, erpnext, erpnext_crm, erpnext_inventory, erpnext_run_report, erpnext_list_reports
esafwan
changed the title
- Dynamic Updates: Removed the restrictive, hardcoded updatable field arrays in _handle_update_lead and _handle_update_opportunity. Updates now dynamically check the ERPNext DocType metadata to allow any valid, non-structural field to be updated safely, including custom fields. - Fuzzy Search: Updated _handle_get_leads search logic to replace spaces with % wildcards.
- Auto-date Resolution: handle_run_report now intercepts fiscal_year arguments and queries the database to auto-inject mandatory from_date, to_date, period_start_date, and period_end_date filters, preventing Frappe backend crashes on financial statements. - Periodicity Fallback: Injected a periodicity: Yearly default fallback to prevent KeyError: None on financial statement generation. - JSON Serialization: Added default=str to json.dumps to prevent crashes when report results return native Python datetime.date objects. - Global Report Search: Added a search parameter to handle_list_reports, allowing the AI to fuzzy-search for report names across all modules simultaneously if it miscategorizes the module.
esafwan
pushed a commit
that referenced
this pull request
Jun 12, 2026
…-tools feat: Add Frappe CRM, Helpdesk, Raven, and ERPNext agent integration tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds agent tools for Frappe apps installed on the same site (Frappe CRM, Helpdesk, Raven, ERPNext). New tools use direct Frappe DocType and report APIs—no external HTTP clients or per-integration credentials. They are registered in the integration tool registry and seeded on install/migrate via existing sync paths.
This branch builds on core communication and developer tools already merged to
developin PR #273. Those 18 tools are unchanged. This PR adds 8 consolidated Frappe/ERPNext tools, for 26 integration tools total.Motivation
Agents need first-class access to business data and workflows inside the Frappe/ERPNext stack: CRM pipelines, helpdesk tickets, internal chat, accounting, inventory, and standard reports. External API wrappers would duplicate auth, add latency, and complicate deployment. In-process Frappe calls reuse site permissions, installed apps, and DocType APIs.
Design
Action-based dispatcher (new tools only)
Each new module exposes a single registry entry with a required
actionparameter.handle_action(**kwargs)routes to private_handle_*implementations. Business logic is unchanged from the initial per-operation implementation; only the public surface and registry shape were consolidated.Benefits:
In-process Frappe integration
httpxor OAuth tokens for these toolsfrappe.get_installed_apps()and returns a structured JSON error if the target app is missingjson.dumps({"success": bool, ...})for consistent agent parsingfrappe.log_errorwith a short tool labelReports: catalogue plus generic runner
Instead of one tool per report, ERPNext reporting is exposed as:
erpnext_list_reports— discover reports by module (90+ entries across 9 modules)erpnext_run_report— run any script/query report viafrappe.desk.query_report.runwith a filters dictRead-only; no document side effects.
Scope boundary with
developAn intermediate commit refactored Slack, Discord, Telegram, GitHub, and recipient tools into the same action pattern. That was reverted: those files match
developexactly. Consolidation applies only to tools introduced in this branch.Tool inventory
Unchanged from
develop(18 tools)get_integration_recipient, 6× Slack, 4× Discord, 1× TelegramNew in this PR (8 tools)
frappe_crmcrm.pyhelpdeskhelpdesk.pyravenraven.pyerpnexterpnext.pyerpnext_crmerpnext_crm.pyerpnext_inventoryerpnext_inventory.pyerpnext_run_reporterpnext_reports.pyerpnext_list_reportserpnext_reports.pyFrappe CRM vs ERPNext CRM: Standalone Frappe CRM uses
CRM Lead/CRM Dealdoctypes (frappe_crm). ERPNext built-in CRM usesLead/Opportunity(erpnext_crm). Categories and tool names are separated so agents do not conflate the two.Files changed
huf/ai/tools/crm.pyhuf/ai/tools/helpdesk.pyhuf/ai/tools/raven.pyhuf/ai/tools/erpnext.pyhuf/ai/tools/erpnext_crm.pyhuf/ai/tools/erpnext_inventory.pyhuf/ai/tools/erpnext_reports.pyhuf/ai/tools/_registry.pyALL_INTEGRATION_TOOLShuf/install.pyApprox. +3,096 lines across 9 files (net of registry edits).
Agent Tool Type categories
New categories created/synced on migrate:
Existing Communication Tools and Developer Tools categories are unchanged.
Prerequisites
frappe_crmcrmin installed appshelpdeskhelpdeskin installed appsravenravenin installed appserpnext,erpnext_crm,erpnext_inventory,erpnext_*_reporterpnextin installed appsAgents should call tools only when the corresponding app is installed; missing apps return
{"success": false, "error": "... not installed"}.Out of scope
develop)develop)Test plan
crm/helpdesk/raven/erpnext: each respective tool returns a clear not-installed errorfrappe_crm):list_leads,create_lead,update_lead,list_deals,add_note,add_taskhelpdesk):create_ticket,get_ticket,add_comment,assign_ticketraven):list_channels,send_message,get_messages(if Raven configured)erpnext):list_customers,get_ledger,list_sales_invoices(read paths)erpnext_crm):list_leads,create_opportunity— verify doctypes are ERPNextLead/Opportunity, not FCRMerpnext_inventory):list_items,stock_balanceerpnext_list_reportswithmodule=Accounts;erpnext_run_reportwithBalance Sheetand validcompany/ date filtersdevelopbehavior)