DOCSEARCHbyAlgolia
Submit Docs

PySpur Documentation

repository·main·Indexed 27 days ago

https://github.com/pyspur-dev/pyspur

PySpur is a Graph UI and AI agent playground for building AI agents in Python. It provides visual debugging, human-in-the-loop capabilities, RAG support, and the ability to deploy agents as APIs. The platform supports data formats including HuggingFace Datasets, CSV, and Blobfile, and includes integrations for Google Sheets and Slack.

Tokens
23.4K
Snippets
51
Records
158
Agent score
91%

What's inside PySpur

  1. Understand the Spur Execution Model

    main

    Spurs use an asynchronous execution engine that differs from traditional Directed Acyclic Graphs (DAGs) in several ways:

    • Cycles: Unlike DAGs, Spurs support cyclic workflows, allowing LLM agents to call themselves or loop through processes until a condition is met.
    • Dynamic Paths: The execution path can change at runtime based on LLM decisions.
    • Asynchronous Execution: Nodes run as soon as their dependencies are satisfied, allowing for parallel execution and preventing the engine from waiting for an entire level of nodes to complete.

  2. Understand the difference between Chatbots and Standard Workflows

    main

    PySpur provides two types of Spurs: Standard Workflows and Chatbots.

    Use Standard Workflows for one-time data processing, automation pipelines, or custom data transformations where you need flexible input/output structures.

    Use Chatbots for conversational interfaces, customer support systems, or virtual assistants that require multi-turn interactions and context retention.

  3. Understand Node fundamentals

    main

    Nodes are the fundamental building blocks of PySpur. They are typed functions that can be used either as components within a workflow or as tools for an agent.

    Each node consists of:

    • Configuration: Defines the node's behavior.
    • Input Schema: A Pydantic model defining required input data.
    • Output Schema: A Pydantic model defining the structure of the result.
    • Execution Logic: The core logic implemented in a run method.

  5. Understand Tools and Nodes in PySpur

    main
    In PySpur, Tools (often referred to interchangeably as Nodes) are the fundamental building blocks used to create workflows. They encapsulate specific logic or functionality and can be combined to automate tasks, build complex workflows, or integrate with external services.

  6. Core Features of PySpur

    main

    PySpur provides several key capabilities for building and deploying AI agents:

    • Test-Driven Development: Build workflows, run test cases, and iterate.
    • Human-in-the-loop: Implement breakpoints where workflows pause for human approval or rejection.
    • Loops: Enable iterative tool calling using memory.
    • RAG (Retrieval-Augmented Generation): Two-step process involving document collection (parsing/chunking) and vector index creation (embedding/upserting to a Vector DB).
    • Multimodal Support: Process video, images, audio, text, and code via file uploads or URLs.
    • Structured Output: Use a UI editor for JSON schemas.
    • Tool Integration: Support for Slack, Firecrawl.dev, Google Sheets, GitHub, and more.
    • Evaluation: Evaluate agents against real datasets.
    • Deployment: One-click deployment to publish as an API.
    • Extensibility: Add new nodes by creating a single Python file.
    • Vendor Agnostic: Supports over 100 LLM providers, embedders, and vector databases.

  7. Understand PySpur evaluation components

    main

    The PySpur evaluation system consists of three core components:

    • Evaluation Benchmarks: Datasets containing problems with known correct answers (ground truth). They define input formatting and how to extract/evaluate outputs. PySpur includes stock benchmarks for mathematical reasoning (GSM8K) and Graduate-level Question answering.
    • Your Workflow: The PySpur workflow being tested, which receives benchmark inputs and returns outputs for comparison.
    • Results and Metrics: Quantitative data generated after running an evaluation, including Accuracy (percentage of correct answers), per-category breakdowns, and example-level success/failure details.

  8. Understand Slack integration options

    main

    PySpur provides two ways to integrate with Slack depending on your needs:

    1. SlackNotifyNode: A one-way communication method where a workflow sends a single result or notification to a Slack channel. Best for alerts and summaries.
    2. Interactive Chatbot: A two-way, bidirectional conversation. This requires a custom Slack app and API integration to manage full conversation history and session management. Best for Q&A and interactive assistance.

  9. Define a workflow using nodes

    main

    You can connect nodes together to create a workflow. The workflow executor manages type validation between connected nodes, dependency resolution, and data flow.

    In a workflow, the output of one node (e.g., input_node) is passed as the input to another (e.g., llm_node) via links.

    # Example of nodes in a workflow
workflow = WorkflowDefinitionSchema(
    nodes=[
        {
            "id": "input_node",
            "title": "User Input",
            "node_type": "InputNode",
            "config": {"output_schema": {"question": "string"}}
        },
        {
            "id": "llm_node",
            "title": "LLM Processing",
            "node_type": "SingleLLMCallNode",
            "config": {
                "system_message": "You are a helpful assistant.",
                "user_message": "{{ question }}"
            }
        }
    ],
    links=[
        {
            "source_id": "input_node",
            "target_id": "llm_node"
        }
    ]
)

  10. Create custom tools using @tool_function

    main

    You can convert any arbitrary Python function into a PySpur tool by using the @tool_function decorator. This allows you to integrate custom logic directly into your PySpur workflows.

    To create a tool:

    1. Create a new .py file in the tools/ directory of your PySpur project.
    2. Define your Python function.
    3. Import tool_function from pyspur.nodes.decorator.
    4. Apply the @tool_function decorator to your function.

    Once decorated, the tool will appear in the PySpur app's tools panel under the specified category.

    from pyspur.nodes.decorator import tool_function

@tool_function(
    name="bar", 
    description="A custom tool example", 
    category="Custom"
)
def foo(param1: str, param2: int = 42) -> dict:
    """A simple example function."""
    return {"param1": param1, "param2": param2}

  11. Understand the RAG workflow in PySpur

    main

    Retrieval Augmented Generation (RAG) in PySpur allows you to ground AI responses in your own data. The workflow consists of three primary stages:

    1. Document Collections: Upload files (PDFs, Word docs, text files, etc.). PySpur extracts text, divides it into chunks, and stores them with metadata.
    2. Vector Indices: Document chunks are converted into mathematical vector embeddings and stored in a vector database to enable semantic search.
    3. Retriever Node: A node in your workflow that takes a query, finds relevant chunks from your vector index, and provides that context to LLM nodes.

  12. Add intelligence to a Chatbot using an LLM node

    main

    To make a chatbot functional, you must connect an LLM (Large Language Model) node between the Input and Output nodes:

    1. Drag an LLM node from the sidebar onto the canvas.
    2. Connect the Input node to the LLM node.
    3. Connect the LLM node to the Output node.
    4. Configure the LLM node by selecting a model provider (e.g., OpenAI, Anthropic) and a specific model (e.g., GPT-4, Claude).
    5. Use a prompt template to reference incoming data using double curly braces.

    Recommended Prompt Template:

    You are a helpful customer support agent for [Your Product].

Previous conversation:
{{message_history}}

User: {{user_message}}

Assistant: