Feat/agents

[srijanpatel]

Agent Node

This PR introduces Agent Node to pyspur. Other nodes can be dropped into this node to let the agent use them as tools.

---

This pull request includes several changes to improve error handling, code readability, and type safety in the backend/pyspur module. The most important changes include adding type casting and assertions, refining exception handling, and enhancing docstrings.

Error Handling Improvements:

• Added assertions to ensure that responses from generate_text are not empty in generate_schema and generate_message functions. [1] [2]
• Enhanced exception handling by chaining exceptions with from e to preserve the original stack trace. [1] [2]

Code Readability Enhancements:

• Split long strings into multiple lines for better readability in generate_schema and generate_message functions. [1] [2] [3] [4] [5] [6] [7] [8]
• Added docstrings and comments to provide better context and explanation for the code changes.

Type Safety Enhancements:

• Added type casting using cast to ensure type correctness in several places, such as schema_str and response. [1] [2]
• Modified the return type of completion_with_backoff to return a Message instead of a str for better type safety. [1] [2]

Miscellaneous Changes:

• Added a new property function_schema to the BaseNode class to convert the config model's schema into a function schema format.
• Added missing imports and updated existing ones to support the new changes. [1] [2]

These changes collectively improve the robustness, readability, and maintainability of the codebase.

---

Important

Introduces AgentNode for LLM-based agents with tool-calling capabilities, improves error handling, code readability, and type safety in pyspur.

• Agent Node:
  • Introduces AgentNode in agent.py for LLM-based agents with tool-calling capabilities.
  • Supports tool calling, iteration control, and tool result feedback.
  • Configured via AgentNodeConfig with subworkflow and max_iterations.
• Error Handling:
  • Adds assertions in generate_schema and generate_message in ai_management.py.
  • Enhances exception handling with from e in ai_management.py.
• Code Readability:
  • Splits long strings in generate_schema and generate_message in ai_management.py.
  • Adds docstrings and comments for clarity.
• Type Safety:
  • Uses cast for type correctness in ai_management.py.
  • Changes return type of completion_with_backoff in _utils.py to Message.
• Miscellaneous:
  • Adds function_schema property to BaseNode in base.py.
  • Updates imports in ai_management.py and workflow_management.py.
  • Adjusts flowSlice in flowSlice.ts for tool management in AgentNode.
  • Enhances NodeSidebar and CollapsibleNodePanel for better UI interaction.

^{This description was created by for e124a8c. It will automatically update as commits are pushed.}

[ellipsis-dev]

❌ Changes requested. Reviewed everything up to 76b209a in 3 minutes and 17 seconds

More details

• Looked at 2394 lines of code in 15 files
• Skipped 0 files when reviewing.
• Skipped posting 16 drafted comments based on config settings.

1. backend/pyspur/api/ai_management.py:125

• Draft comment:
  Good improvements in error chaining and type assertions. Consider using logger consistently instead of print for production errors.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

2. backend/pyspur/nodes/llm/_utils.py:395

• Draft comment:
  The multiline f-string for encoding DOCX XML content is fragile; verify that the formatting works in all environments.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50%
  The comment is asking the PR author to verify the formatting works in all environments, which violates the rule against asking the author to ensure behavior is intended or tested. It does not provide a specific suggestion or point out a specific issue with the code.

3. backend/pyspur/nodes/llm/single_llm_call.py:60

• Draft comment:
  The repair_json function uses multiple regex substitutions that might be brittle; document assumptions and add tests for edge cases.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

4. frontend/src/components/nodes/BaseNode.tsx:1

• Draft comment:
  Component structure is solid. Using deep equality (isEqual) is appropriate, but monitor performance for large data sets.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50%
  The comment is purely informative, suggesting to monitor performance without providing a specific action or suggestion. It doesn't ask for a specific change or confirm an intention, which violates the rules.

5. frontend/src/components/nodes/CollapsibleNodePanel.tsx:50

• Draft comment:
  Good use of controlled expansion state and hotkeys. Ensure the panel is accessible for keyboard navigation.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50%
  The comment is asking the PR author to ensure accessibility, which is similar to asking them to double-check or verify something. This violates the rule against asking the author to ensure something is tested or verified.

6. frontend/src/components/nodes/NodeErrorDisplay.tsx:16

• Draft comment:
  Consider a fallback to display raw error when JSON parsing fails. The error display design is clear and concise.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

7. frontend/src/components/nodes/agent/AgentNode.tsx:80

• Draft comment:
  Agent node handles tool instantiation well. Ensure unique keys in tools_dict to avoid collisions.
• Reason this comment was not posted:
  Comment was on unchanged code.

8. frontend/src/components/nodes/nodeSidebar/NodeSidebar.tsx:106

• Draft comment:
  The validateJsonSchema function extracts detailed error info; ensure the regex for extracting error positions works consistently across browsers.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

9. frontend/src/store/flowSlice.ts:290

• Draft comment:
  Flow slice reducers are well organized. When rebuilding router or coalesce schemas, consider using immer for safer immutability handling.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

10. frontend/src/utils/flowUtils.tsx:90

• Draft comment:
  The node ID generation and sanitization functions are clear; ensure consistency in sanitizing node type names across different node types.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

11. backend/pyspur/nodes/llm/agent.py:127

• Draft comment:
  Consider using a union type for the 'tools' parameter (e.g. Array<WorkflowNodeSchema | BaseNode>) rather than a union of two separate lists. This will help simplify type handling and avoid potential type inconsistencies.
• Reason this comment was not posted:
  Comment looked like it was already resolved.

12. backend/pyspur/nodes/llm/single_llm_call.py:42

• Draft comment:
  The regex‐based approach in repair_json for converting single quotes to double quotes can be brittle. Consider using a more robust JSON repair method or a dedicated library to avoid edge case issues.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

13. frontend/src/components/nodes/nodeSidebar/NodeSidebar.tsx:50

• Draft comment:
  The NodeSidebar component is quite complex and lengthy. It is recommended to refactor it into smaller, modular components to improve maintainability and readability.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

14. frontend/src/store/flowSlice.ts:295

• Draft comment:
  The transformation applied to 'nodeTypeName' in addToolToAgent (replacing spaces with underscores and 'Node' with 'Tool') is not documented. Consider adding inline comments to explain the rationale behind this transformation.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50%
  The transformation of nodeTypeName is a straightforward string manipulation to ensure a consistent and unique ID format. While the transformation is not explicitly documented, it is a common practice to sanitize strings for ID generation. The comment does not point out a code issue but suggests adding documentation, which is not a strong requirement for code functionality.
  The transformation might be self-explanatory to experienced developers, and adding comments for every transformation could lead to clutter. However, for less experienced developers, understanding the rationale might be beneficial.
  While the transformation is simple, providing a brief comment could improve code readability for all developers, especially those new to the codebase.
  The comment does not indicate a code issue but suggests an improvement for documentation. It is not strictly necessary for functionality, so it should be removed.

15. frontend/src/utils/flowUtils.tsx:105

• Draft comment:
  In createNodeAtCenter, ensure that node placement remains responsive across different screen sizes. Consider additional testing or dynamic adjustments so that node positioning behaves correctly on various devices.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

16. backend/pyspur/api/ai_management.py:225

• Draft comment:
  In the user message triple-quoted string and related f-string continuations, backslashes are used to split the string across lines. This can result in missing spaces between parts of the string (for example, between 'AI' and 'assistants' or 'based' and 'on'). Please ensure that appropriate spacing is maintained either by including a space before the backslash or at the start of the next line.
• Reason this comment was not posted:
  Marked as duplicate.

Workflow ID: wflow_4CEBthSvwoPsoygl

---

Want Ellipsis to fix these issues? Tag @ellipsis-dev in a comment. You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.

[ellipsis-dev]

👍 Looks good to me! Incremental review on 56523b9 in 32 seconds

More details

• Looked at 132 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 2 drafted comments based on config settings.

1. backend/pyspur/templates/.env.example:1

• Draft comment:
  Removal of .env.example: This file typically serves as a guide for setting up environment variables for both development and production. Its deletion might confuse new developers or users relying on it for configuration references. If intended, please document the alternative approach or update related documentation.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

2. backend/pyspur/templates/.env.example:1

• Draft comment:
  The deletion of the .env.example file may remove a useful reference for configuration. This template file is often valuable for new developers to understand required environment variables. If its removal is intentional, please ensure that updated documentation or an alternative template is provided.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

Workflow ID: wflow_xc1ivOFRPFia7wiQ

---

You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.

[ellipsis-dev]

👍 Looks good to me! Incremental review on e124a8c in 1 minute and 44 seconds

More details

• Looked at 13 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 2 drafted comments based on config settings.

1. backend/pyspur/api/ai_management.py:176

• Draft comment:
  Added a space after 'effective' in the system message string to ensure proper spacing when concatenating the text. This fix improves readability and avoids an unintended word merge.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50%
  This comment is purely informative, explaining a change that was made. It doesn't suggest any action or ask for confirmation, which violates the rules.

2. backend/pyspur/api/ai_management.py:176

• Draft comment:
  Minor fix: Adding a trailing space after the backslash prevents words from running together. Consider if using triple-quoted strings with inherent newlines might simplify multi-line string formatting.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50%
  None

Workflow ID: wflow_NwM5f7EopmhnSKbh

---

You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.