Frappe Agent Interpreter

Frappe Code Interpreter Agent

Transforms vague or incomplete Frappe/ERPNext development requests into clear, actionable technical specifications mapped to the full 61-skill catalog.

Purpose: Bridge the gap between "what the user wants" and "what needs to be built"

When to Use This Agent

USER REQUEST ANALYSIS
|
+-- Request is vague/incomplete
|   "Make the invoice do something when submitted"
|   --> USE THIS AGENT
|
+-- Request lacks technical specifics
|   "Add approval before order confirmation"
|   --> USE THIS AGENT
|
+-- Multiple implementation paths possible
|   "Automate inventory updates"
|   --> USE THIS AGENT
|
+-- Request has clear technical specs already
|   "Create Server Script on validate for Sales Invoice"
|   --> Skip agent, use relevant frappe-* skills directly

Interpretation Workflow

STEP 1: EXTRACT INTENT
  - What is the business problem?
  - What should happen? When? To what data?
  - Who should be affected (roles/users)?

STEP 2: IDENTIFY TRIGGER CONTEXT
  - Document lifecycle event? (save/submit/cancel)
  - User action? (button click, field change)
  - Time-based? (daily, hourly, cron)
  - External event? (webhook, API call)

STEP 3: DETERMINE MECHANISM
  - Client Script, Server Script, or Controller?
  - Hooks configuration needed?
  - Custom app required?
  - v16 extend_doctype_class applicable?

STEP 4: GENERATE SPECIFICATION
  - DocType(s), event/trigger, mechanism, data flow
  - Error handling requirements
  - Version compatibility (v14/v15/v16)

STEP 5: MAP TO SKILLS
  - List required frappe-* skills from full catalog
  - Note dependencies between skills

See references/workflow.md for detailed steps.

Mechanism Selection Matrix

Clarifying Questions Framework

1. WHAT Questions

• What DocType(s) are involved?
• What data needs to change?
• What should the outcome be?

2. WHEN Questions

• On form load? On field change? Before/after save?
• Before/after submit? On a schedule? Button click?

3. WHO Questions

• All users? Specific roles? Document owner only?

4. WHERE Questions

• In the form (UI)? Database only? Report? External system?

5. ERROR Questions

• Block the operation? Show warning? Log silently?

6. VERSION Questions (v16 considerations)

• Target single version or multi-version compatibility?
• Can we use extend_doctype_class (v16) or need doc_events (v14+)?
• Type annotations desired? (v16 best practice)

Output Specification Template

ALWAYS generate specifications in this format:

## Technical Specification

### Summary
[One sentence describing what will be built]

### Business Requirement
[Original user request, clarified]

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | [List] |
| **Trigger** | [Event/action] |
| **Mechanism** | [Client Script / Server Script / Controller / etc.] |
| **Version** | [v14 / v15 / v16 / all] |

### Data Flow
1. [Step 1]
2. [Step 2]

### Error Handling
[Strategy]

### Required Skills
- [ ] frappe-skill-name - for [purpose]

### Validation Criteria
[How to verify it works]

Complete Skill Catalog (61 skills)

Syntax Layer (11 skills)

Core Layer (7 skills)

Implementation Layer (12 skills)

Error Layer (7 skills)

Ops Layer (8 skills)

Testing Layer (2 skills)

Agent Layer (5 skills)

Skill Dependencies Map

Common Pattern Recognition

Version Awareness

ALWAYS consider version compatibility:

Agent Output Checklist

Before completing interpretation, ALWAYS verify:

• [ ] Business requirement is clear and unambiguous
• [ ] Trigger/event is identified
• [ ] Mechanism is selected with justification
• [ ] DocType(s) are specified
• [ ] Data flow is documented
• [ ] Error handling approach is defined
• [ ] Version compatibility is noted (v14/v15/v16)
• [ ] Required frappe-* skills are listed from full catalog
• [ ] Validation criteria are defined
• [ ] v16 considerations noted (extend_doctype_class, type annotations)

See references/checklists.md for detailed checklists. See references/examples.md for interpretation examples.

Code Interpreter Checklists

Pre-Interpretation Checklist

Before starting interpretation, verify:

• [ ] User request is captured completely
• [ ] No obvious typos or misunderstandings
• [ ] Context is sufficient (which DocTypes, which Frappe version)
• [ ] If unclear: clarifying questions prepared

---

Step 1 Checklist: Extract Intent

Action Identification

• [ ] Primary action verb identified
• [ ] Action mapped to category:
• [ ] Computation/calculation
• [ ] Validation/prevention
• [ ] Notification/communication
• [ ] Integration/sync
• [ ] Filtering/permission
• [ ] Workflow/approval
• [ ] UI customization
• [ ] Scheduling/automation
• [ ] Reporting/analytics
• [ ] Website/portal
• [ ] File handling
• [ ] Deployment/ops
• [ ] Testing

Subject Identification

• [ ] Primary DocType(s) identified
• [ ] Related DocType(s) identified (if any)
• [ ] Specific field(s) mentioned (if any)
• [ ] Data transformation described (if any)

Condition Identification

• [ ] Trigger condition clear (when should this happen?)
• [ ] Filter conditions clear (for which records?)
• [ ] User/role conditions clear (for whom?)

---

Step 2 Checklist: Identify Trigger

Trigger Type Confirmed

• [ ] User action on form
• [ ] Field change
• [ ] Form load
• [ ] Button click
• [ ] Save
• [ ] Submit
• [ ] Cancel
• [ ] Time/schedule
• [ ] Frequency identified
• [ ] Cron pattern determined
• [ ] External event
• [ ] Webhook
• [ ] API call
• [ ] Other app trigger
• [ ] Permission check
• [ ] List filtering
• [ ] Document access

Timing Confirmed

• [ ] Before action (can block)
• [ ] After action (cannot block, only react)

---

Step 3 Checklist: Determine Mechanism

Server Script Eligibility

• [ ] No external library imports needed
• [ ] No complex transaction management needed
• [ ] No file system access needed
• [ ] No shell commands needed
• [ ] --> Server Script is eligible (all checked)
• [ ] --> Controller required (any unchecked)

v16 Considerations

• [ ] Target version identified (v14, v15, v16, or multi)
• [ ] extend_doctype_class considered if v16-only
• [ ] Type annotations considered if v16
• [ ] Data masking considered for PII fields

Mechanism Selection

• [ ] Primary mechanism selected:
• [ ] Client Script
• [ ] Server Script (Document Event)
• [ ] Server Script (API)
• [ ] Server Script (Scheduler)
• [ ] Server Script (Permission Query)
• [ ] Controller
• [ ] hooks.py configuration
• [ ] Built-in feature (Workflow, Notification, etc.)
• [ ] Report (Script/Query)
• [ ] Website template
• [ ] Integration pattern
• [ ] Selection justified with reasoning
• [ ] Custom app requirement identified (yes/no)

---

Step 4 Checklist: Generate Specification

Specification Completeness

• [ ] Summary (1 sentence)
• [ ] Business requirement (clarified)
• [ ] Implementation table:
• [ ] DocType(s) listed
• [ ] Trigger specified
• [ ] Mechanism named
• [ ] Version compatibility noted
• [ ] Data flow documented (numbered steps)
• [ ] Error handling defined

Data Flow Quality

• [ ] Input data sources identified
• [ ] Processing steps clear
• [ ] Output/side effects documented
• [ ] No missing steps in flow

Error Handling Quality

• [ ] Possible errors identified
• [ ] Each error has handling strategy
• [ ] User feedback approach defined
• [ ] Logging requirements noted

---

Step 5 Checklist: Map to Skills

Primary Skills (syntax + implementation)

• [ ] Syntax skill for mechanism (frappe-syntax-*)
• [ ] Implementation skill for mechanism (frappe-impl-*)
• [ ] Error handling skill for mechanism (frappe-errors-*)

Core Skills (if needed)

• [ ] Database operations (frappe-core-database)
• [ ] Permission handling (frappe-core-permissions)
• [ ] API patterns (frappe-core-api)
• [ ] Workflow engine (frappe-core-workflow)
• [ ] Notifications (frappe-core-notifications)
• [ ] File handling (frappe-core-files)
• [ ] Cache operations (frappe-core-cache)

Ops Skills (if needed)

• [ ] Bench commands (frappe-ops-bench)
• [ ] Deployment (frappe-ops-deployment)
• [ ] Performance (frappe-ops-performance)
• [ ] Backup (frappe-ops-backup)
• [ ] Upgrades (frappe-ops-upgrades)

Testing Skills (if needed)

• [ ] Unit tests (frappe-testing-unit)
• [ ] CI/CD (frappe-testing-cicd)

Agent Skills (if needed)

• [ ] Code validation (frappe-agent-validator)
• [ ] Debugging (frappe-agent-debugger)
• [ ] Architecture (frappe-agent-architect)
• [ ] Migration (frappe-agent-migrator)

Skill Dependencies

• [ ] Dependencies between skills noted
• [ ] Order of skill usage clear

---

Output Quality Checklist

Clarity

• [ ] Non-technical user can understand the summary
• [ ] Technical implementer can follow the specification
• [ ] No ambiguous terms or undefined acronyms

Completeness

• [ ] All aspects of request addressed
• [ ] Edge cases considered
• [ ] Version compatibility explicit (v14/v15/v16)

Actionability

• [ ] Clear next steps for implementation
• [ ] Required frappe-* skills listed from full catalog
• [ ] Validation criteria defined

---

Quick Reference: Mechanism --> Skills

Code Interpreter Examples

Example 1: Auto-Calculate Request

User Input

"I want the total weight to automatically calculate based on item weights in the Sales Order"

Interpretation Process

Extract Intent:

• Action: Auto-calculate (field computation)
• Subject: Total weight field, item weights in Sales Order
• Condition: When items change

Identify Trigger:

• Field change (item added/removed/modified) --> Client Script
• Before save (validation backup) --> Server Script

Determine Mechanism:

• Real-time UI update needed --> Client Script
• Save validation needed --> Server Script
• No external libraries --> Server Script OK

Generated Specification

## Technical Specification

### Summary
Auto-calculate total weight in Sales Order based on sum of item weights.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Sales Order, Sales Order Item |
| **Trigger** | Item table change + before save |
| **Mechanism** | Client Script + Server Script |
| **Version** | v14/v15/v16 |

### Data Flow
1. User modifies items table (add/remove/change qty)
2. Client Script triggers calculation
3. Sum: qty x weight_per_unit for each item
4. Update total_weight field
5. On save: Server Script recalculates and validates

### Error Handling
- Missing weight_per_unit: treat as 0, no error
- Negative result: frappe.throw() on save

### Required Skills
- [x] frappe-syntax-clientscripts
- [x] frappe-impl-clientscripts
- [x] frappe-syntax-serverscripts
- [x] frappe-impl-serverscripts

---

Example 2: Notification Request

User Input

"Send email to manager when purchase order exceeds $10,000"

Generated Specification

## Technical Specification

### Summary
Email notification to manager when Purchase Order grand_total exceeds $10,000.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Purchase Order |
| **Trigger** | on_submit |
| **Mechanism** | Server Script (Document Event) |
| **Version** | v14/v15/v16 |

### Data Flow
1. User submits Purchase Order
2. Server Script checks if grand_total > 10000
3. If yes: frappe.sendmail() to manager

### Required Skills
- [x] frappe-syntax-serverscripts
- [x] frappe-impl-serverscripts
- [x] frappe-core-notifications

### Alternative: No-Code Solution
Use Notification DocType: Document Type = Purchase Order, Event = Submit, Condition = doc.grand_total > 10000

---

Example 3: External Integration Request

User Input

"Sync inventory to our warehouse system via API when stock moves"

Generated Specification

## Technical Specification

### Summary
Sync stock movements to external warehouse system via REST API on Stock Entry submission.

### CRITICAL: Custom App Required
Server Scripts CANNOT import the `requests` library.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Stock Entry |
| **Trigger** | on_submit |
| **Mechanism** | Controller (custom app) |
| **Version** | v14/v15/v16 |

### Data Flow
1. Stock Entry submitted
2. Controller's on_submit hook triggers
3. Transform data to external API format
4. POST to external warehouse API
5. Log response; if failure: enqueue retry

### Required Skills
- [x] frappe-impl-customapp - Custom app structure
- [x] frappe-impl-integrations - Integration patterns
- [x] frappe-syntax-controllers - Controller class
- [x] frappe-impl-controllers - on_submit implementation
- [x] frappe-errors-controllers - Error handling
- [x] frappe-syntax-hooks - doc_events configuration
- [x] frappe-impl-scheduler - Retry queue (if needed)

---

Example 4: Permission Filtering Request

User Input

"Sales reps should only see their own customers"

Generated Specification

## Technical Specification

### Summary
Filter Customer list view to show only customers assigned to the current sales representative.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Customer |
| **Trigger** | List view access |
| **Mechanism** | Server Script (Permission Query) |
| **Version** | v14/v15/v16 |

### Required Skills
- [x] frappe-syntax-serverscripts - Permission Query syntax
- [x] frappe-core-permissions - Permission patterns
- [x] frappe-errors-permissions - Permission error handling

---

Example 5: Workflow Request

User Input

"Purchase orders over $5000 need manager approval before submission"

Generated Specification

## Technical Specification

### Summary
Approval workflow for Purchase Orders exceeding $5,000.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Purchase Order |
| **Trigger** | Document state changes |
| **Mechanism** | Built-in Workflow + optional Server Script |
| **Version** | v14/v15/v16 |

### States
1. Draft (default) 2. Pending Approval 3. Approved 4. Submitted 5. Rejected

### Required Skills
- [x] frappe-core-workflow - Workflow engine
- [x] frappe-impl-workflow - Workflow implementation
- [x] frappe-syntax-serverscripts - Optional custom logic

---

Example 6: Scheduled Task Request

User Input

"Every night, check for overdue invoices and send reminders"

Generated Specification

## Technical Specification

### Summary
Daily scheduled task to identify overdue Sales Invoices and send payment reminders.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Sales Invoice |
| **Trigger** | Cron: 0 2 * * * (daily at 2 AM) |
| **Mechanism** | hooks.py scheduler_events (custom app) |
| **Version** | v14/v15/v16 |

### Required Skills
- [x] frappe-impl-scheduler - Scheduler implementation
- [x] frappe-syntax-scheduler - Cron syntax
- [x] frappe-impl-customapp - App structure
- [x] frappe-core-database - Query patterns
- [x] frappe-core-notifications - Email sending

---

Example 7: Report Request

User Input

"I need a report showing monthly sales by territory with drill-down"

Generated Specification

## Technical Specification

### Summary
Script Report for monthly sales analysis by territory with drill-down capability.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Sales Invoice |
| **Trigger** | User opens report |
| **Mechanism** | Script Report |
| **Version** | v14/v15/v16 |

### Required Skills
- [x] frappe-syntax-reports - Report definition
- [x] frappe-impl-reports - Report building patterns
- [x] frappe-core-database - Aggregation queries

---

Example 8: Deployment/Ops Request

User Input

"How do I deploy my custom app to production?"

Generated Specification

## Technical Specification

### Summary
Production deployment workflow for custom Frappe app.

### Implementation Steps
1. Prepare app for distribution (git, pyproject.toml)
2. Set up production bench
3. Install app on production site
4. Configure supervisor and nginx
5. Enable scheduler, set up backups

### Required Skills
- [x] frappe-ops-deployment - Deployment procedures
- [x] frappe-ops-bench - Bench commands
- [x] frappe-ops-backup - Backup configuration
- [x] frappe-ops-performance - Production tuning
- [x] frappe-impl-customapp - App packaging

---

Pattern Recognition Summary

Code Interpreter Workflow - Detailed Steps

Complete Interpretation Process

Step 1: Extract Intent

Goal: Understand what the user actually wants to achieve.

1.1 Identify the Action Verb

1.2 Identify the Subject

What data/document is involved?

• Specific DocType mentioned?
• Field names mentioned?
• Related documents involved?

1.3 Identify the Condition

When should this happen?

• Always?
• Only when specific field has value?
• Only for specific status?
• Only for specific user/role?

Step 2: Identify Trigger Context

Goal: Determine WHEN the code should execute.

Decision Tree: Trigger Type

Is it triggered by...

USER ACTION ON FORM?
+-- Field value change
|   --> Client Script: on field change
+-- Form load
|   --> Client Script: refresh event
+-- Button click
|   --> Client Script: custom button with frappe.call
+-- Save button
|   --> Server Script: validate (before) or on_update (after)
+-- Submit button
|   --> Server Script: before_submit or on_submit
+-- Cancel button
    --> Server Script: before_cancel or on_cancel

TIME/SCHEDULE?
+-- Every X minutes/hours
|   --> Server Script Scheduler or hooks.py
+-- Daily at specific time
|   --> Server Script Scheduler (cron) or hooks.py
+-- Weekly/Monthly
    --> hooks.py scheduler_events

EXTERNAL EVENT?
+-- Webhook from external system
|   --> Server Script API or @frappe.whitelist
+-- API call
|   --> Server Script API or @frappe.whitelist
+-- Another app's action
    --> doc_events in hooks.py

PERMISSION CHECK?
+-- List view filtering
    --> Server Script Permission Query

Step 3: Determine Mechanism

Goal: Select the right Frappe mechanism.

Primary Decision: Server Script vs Controller

CAN YOU USE SERVER SCRIPT?

Check these disqualifiers:
[ ] Need to import external library (requests, pandas, etc.)
[ ] Need complex try/except/finally with rollback
[ ] Need to modify multiple documents in transaction
[ ] Need to access file system
[ ] Need to run shell commands

If ANY checked --> Controller (custom app required)
If NONE checked --> Server Script acceptable

Secondary Decision: Client Script Needed?

ADD CLIENT SCRIPT WHEN:
[ ] Real-time UI feedback needed (instant calculation)
[ ] Field visibility/read-only based on other fields
[ ] Custom buttons needed
[ ] Form-level warnings/alerts
[ ] Auto-fetch from linked documents

v16 Decision: extend_doctype_class vs doc_events

TARGETING v16 ONLY?
+-- YES --> Use extend_doctype_class (cleaner, supports mixins)
+-- NO --> Use doc_events (works on v14/v15/v16)

Mechanism Selection Summary

Step 4: Generate Specification

Goal: Create actionable technical spec.

Specification Components

1. Summary (1 sentence) - What will be built, what problem it solves 2. Business Requirement (clarified) - Original request with ambiguities resolved 3. Implementation Details - DocType(s), trigger, mechanism, version 4. Data Flow - Read, process, write, output steps 5. Error Handling - What errors can occur, how handled 6. Validation Criteria - How to test it works, edge cases

Step 5: Map to Skills

Goal: Identify which frappe-* skills are needed for implementation.

Skill Mapping Process

1. Based on mechanism, identify PRIMARY skills (syntax + impl) 2. Add ERROR HANDLING skills (frappe-errors-*) 3. Add CORE skills if needed (database, permissions, api, etc.) 4. Add OPS skills if deployment is involved 5. Add TESTING skills if test coverage requested 6. Check for CUSTOM APP requirement (frappe-impl-customapp) 7. Consider AGENT skills (frappe-agent-validator for review)

Example Interpretation Walkthrough

Input Request

"When a Sales Invoice is submitted, check if customer credit limit is exceeded and block if so"

Step 1: Extract Intent

• Action: "check" and "block" --> Validation that prevents action
• Subject: Sales Invoice, Customer credit limit
• Condition: On submit

Step 2: Identify Trigger

• User action: Submit button
• Trigger: before_submit (must block BEFORE action completes)

Step 3: Determine Mechanism

• No external libraries needed
• No complex transactions needed
• --> Server Script is acceptable

Step 4: Generate Specification

## Technical Specification

### Summary
Block Sales Invoice submission when customer's credit limit is exceeded.

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | Sales Invoice, Customer |
| **Trigger** | before_submit |
| **Mechanism** | Server Script (Document Event) |
| **Version** | v14/v15/v16 |

### Data Flow
1. Get customer from Sales Invoice
2. Query customer's current outstanding amount
3. Add current invoice grand_total
4. Compare with customer's credit_limit
5. If exceeded: frappe.throw() with message

### Required Skills
- [x] frappe-syntax-serverscripts
- [x] frappe-impl-serverscripts
- [x] frappe-errors-serverscripts
- [x] frappe-core-database

Step 5: Map to Skills

• Primary: frappe-syntax-serverscripts, frappe-impl-serverscripts
• Error: frappe-errors-serverscripts
• Supporting: frappe-core-database (for outstanding calculation)
• Validation: frappe-agent-validator (review before deployment)