puffinflow 2.dev0__tar.gz

puffinflow-2.dev0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,115 @@
+---
+name: Bug Report
+about: Create a report to help us improve PuffinFlow
+title: '[BUG] '
+labels: ['bug', 'needs-triage']
+assignees: ''
+---
+
+## Bug Description
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Actual behavior**
+A clear and concise description of what actually happened.
+
+## Reproduction Steps
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Minimal code example**
+```python
+# Please provide a minimal code example that reproduces the issue
+from puffinflow import Agent
+
+# Your code here
+```
+
+## Environment Information
+
+**PuffinFlow version:**
+<!-- Run: pip show puffinflow -->
+
+**Python version:**
+<!-- Run: python --version -->
+
+**Operating System:**
+<!-- e.g., Ubuntu 20.04, Windows 10, macOS 12.0 -->
+
+**Installation method:**
+- [ ] pip
+- [ ] conda
+- [ ] from source
+- [ ] other (please specify)
+
+**Optional dependencies installed:**
+- [ ] observability
+- [ ] integrations
+- [ ] cli
+- [ ] all
+- [ ] none
+
+## Additional Context
+
+**Error messages/logs**
+```
+Paste any error messages or relevant log output here
+```
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Stack trace**
+```
+If there's a stack trace, paste it here
+```
+
+**Configuration**
+```python
+# If relevant, share your configuration
+```
+
+**Additional context**
+Add any other context about the problem here.
+
+## Checklist
+
+- [ ] I have searched existing issues to ensure this is not a duplicate
+- [ ] I have provided a minimal code example that reproduces the issue
+- [ ] I have included the PuffinFlow version and Python version
+- [ ] I have included relevant error messages or logs
+- [ ] I have checked the documentation and this issue is not covered there
+
+## Possible Solution
+
+<!-- Optional: If you have ideas on how to fix this bug, please describe them here -->
+
+## Impact
+
+**Severity:**
+- [ ] Critical (blocks core functionality)
+- [ ] High (significantly impacts functionality)
+- [ ] Medium (some functionality affected)
+- [ ] Low (minor issue or cosmetic)
+
+**Frequency:**
+- [ ] Always
+- [ ] Often
+- [ ] Sometimes
+- [ ] Rarely
+
+**Workaround available:**
+- [ ] Yes (please describe below)
+- [ ] No
+
+**Workaround description:**
+<!-- If you found a workaround, please describe it here -->

puffinflow-2.dev0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,139 @@
+name: 🐛 Bug Report
+description: Create a report to help us improve PuffinFlow
+title: "[Bug]: "
+labels: ["bug", "needs-triage"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report a bug! Please fill out this form completely to help us understand and reproduce the issue.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Prerequisites
+      description: Please confirm the following before submitting
+      options:
+        - label: I have searched existing issues to ensure this bug hasn't been reported
+          required: true
+        - label: I have read the documentation
+          required: true
+        - label: I am using a supported version of PuffinFlow
+          required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: PuffinFlow Version
+      description: What version of PuffinFlow are you using?
+      placeholder: "e.g., 1.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: What version of Python are you using?
+      placeholder: "e.g., 3.11.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      description: What operating system are you using?
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other (please specify in description)
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Create an agent with '...'
+        2. Execute state '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen
+      placeholder: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: A clear and concise description of what actually happened
+      placeholder: What actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Minimal Reproducible Example
+      description: Please provide a minimal code example that reproduces the issue
+      render: python
+      placeholder: |
+        from puffinflow import Agent
+
+        # Your minimal example here
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs
+      description: If applicable, add error logs or stack traces
+      render: text
+      placeholder: Paste your error logs here...
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here
+      placeholder: Any other relevant information...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How severe is this bug?
+      options:
+        - Critical (application crashes, data loss)
+        - High (major functionality broken)
+        - Medium (feature partially broken)
+        - Low (minor issue, workaround available)
+    validations:
+      required: true

puffinflow-2.dev0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,152 @@
+---
+name: Feature Request
+about: Suggest an idea or enhancement for PuffinFlow
+title: '[FEATURE] '
+labels: ['enhancement', 'needs-triage']
+assignees: ''
+---
+
+## Feature Summary
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Detailed Description
+
+**Use case**
+Describe the specific use case or scenario where this feature would be beneficial.
+
+**Expected behavior**
+Describe in detail how you expect this feature to work.
+
+**API design (if applicable)**
+```python
+# If this involves new APIs, provide a rough sketch of how you'd like them to work
+from puffinflow import SomeNewFeature
+
+# Example usage
+feature = SomeNewFeature(config="example")
+result = feature.do_something()
+```
+
+## Implementation Considerations
+
+**Components affected**
+Which parts of PuffinFlow would this feature affect?
+- [ ] Core agents
+- [ ] Coordination system
+- [ ] Resource management
+- [ ] Observability
+- [ ] Reliability features
+- [ ] CLI tools
+- [ ] Documentation
+- [ ] Other (please specify)
+
+**Breaking changes**
+- [ ] This feature would require breaking changes
+- [ ] This feature is backward compatible
+- [ ] Unsure
+
+**Performance impact**
+- [ ] No performance impact expected
+- [ ] Minor performance impact
+- [ ] Significant performance impact
+- [ ] Performance improvement expected
+- [ ] Unsure
+
+## Priority and Impact
+
+**Priority level**
+- [ ] Critical (core functionality missing)
+- [ ] High (important for many users)
+- [ ] Medium (nice to have)
+- [ ] Low (minor enhancement)
+
+**User impact**
+- [ ] Affects all users
+- [ ] Affects most users
+- [ ] Affects some users
+- [ ] Affects few users (niche use case)
+
+**Complexity estimate**
+- [ ] Simple (few hours of work)
+- [ ] Medium (few days of work)
+- [ ] Complex (weeks of work)
+- [ ] Very complex (months of work)
+- [ ] Unsure
+
+## Additional Context
+
+**Related issues/PRs**
+<!-- Link any related issues or pull requests -->
+
+**External references**
+<!-- Links to relevant documentation, papers, or other projects -->
+
+**Screenshots/mockups**
+<!-- If applicable, add screenshots or mockups to help explain your feature -->
+
+**Additional context**
+Add any other context, screenshots, or examples about the feature request here.
+
+## Acceptance Criteria
+
+**Definition of Done**
+What would need to be implemented for this feature to be considered complete?
+
+- [ ] Core functionality implemented
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] Examples provided
+- [ ] Performance benchmarks (if applicable)
+- [ ] Migration guide (if breaking changes)
+
+**Testing requirements**
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Performance tests
+- [ ] Manual testing scenarios
+
+## Implementation Ideas
+
+**Potential approach**
+<!-- If you have ideas on how this could be implemented, share them here -->
+
+**Code references**
+<!-- If you've identified specific files or functions that would need changes -->
+
+**Dependencies**
+<!-- Any new dependencies that might be required -->
+
+## Community Input
+
+**Would you be willing to contribute to this feature?**
+- [ ] Yes, I can implement this
+- [ ] Yes, I can help with testing
+- [ ] Yes, I can help with documentation
+- [ ] Yes, I can help with design/planning
+- [ ] No, but I'd be happy to provide feedback
+- [ ] No, I'm just requesting the feature
+
+**Timeline**
+When would you need this feature?
+- [ ] ASAP
+- [ ] Within a month
+- [ ] Within 3 months
+- [ ] Within 6 months
+- [ ] No specific timeline
+- [ ] Other (please specify)
+
+## Checklist
+
+- [ ] I have searched existing issues to ensure this is not a duplicate
+- [ ] I have provided a clear description of the problem and proposed solution
+- [ ] I have considered the impact and complexity of this feature
+- [ ] I have checked if this feature aligns with PuffinFlow's goals and scope
+- [ ] I have provided sufficient context and examples

puffinflow-2.dev0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,147 @@
+name: ✨ Feature Request
+description: Suggest a new feature or enhancement for PuffinFlow
+title: "[Feature]: "
+labels: ["enhancement", "needs-discussion"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a new feature! Please provide as much detail as possible to help us understand your request.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Prerequisites
+      description: Please confirm the following before submitting
+      options:
+        - label: I have searched existing issues and discussions to ensure this feature hasn't been requested
+          required: true
+        - label: I have read the project roadmap and this feature isn't already planned
+          required: true
+        - label: This feature would benefit the broader PuffinFlow community
+          required: true
+
+  - type: dropdown
+    id: feature-type
+    attributes:
+      label: Feature Type
+      description: What type of feature is this?
+      options:
+        - New API/functionality
+        - Performance improvement
+        - Developer experience enhancement
+        - Documentation improvement
+        - Integration with external service
+        - Other (please specify in description)
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve? What pain point does it address?
+      placeholder: Describe the problem or limitation you're experiencing...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe your proposed solution in detail
+      placeholder: How would you like to see this problem solved?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternative Solutions
+      description: Describe any alternative solutions or workarounds you've considered
+      placeholder: What other approaches have you considered?
+    validations:
+      required: false
+
+  - type: textarea
+    id: use-cases
+    attributes:
+      label: Use Cases
+      description: Describe specific use cases where this feature would be valuable
+      placeholder: |
+        1. When building agents that...
+        2. When orchestrating workflows that...
+        3. When debugging systems that...
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-design
+    attributes:
+      label: API Design (if applicable)
+      description: If this is an API change, show what the API might look like
+      render: python
+      placeholder: |
+        # Example API design
+        agent = Agent("my-agent")
+        agent.new_feature(parameter="value")
+    validations:
+      required: false
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: How important is this feature to you?
+      options:
+        - Critical (blocking my use case)
+        - High (would significantly improve my workflow)
+        - Medium (nice to have)
+        - Low (minor improvement)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: complexity
+    attributes:
+      label: Implementation Complexity (your estimate)
+      description: How complex do you think this feature would be to implement?
+      options:
+        - Low (simple addition/change)
+        - Medium (moderate effort required)
+        - High (significant changes needed)
+        - Unknown
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: breaking-changes
+    attributes:
+      label: Breaking Changes
+      description: Would this feature require breaking changes?
+      options:
+        - label: This feature could be implemented without breaking existing functionality
+        - label: This feature might require breaking changes (please explain in additional context)
+        - label: I'm not sure about breaking changes
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or examples about the feature request
+      placeholder: Any additional information that might be helpful...
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      description: Are you willing to help implement this feature?
+      options:
+        - label: I would be willing to submit a PR for this feature
+        - label: I would be willing to help with testing
+        - label: I would be willing to help with documentation
+        - label: I prefer to leave implementation to maintainers

puffinflow-2.dev0/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,156 @@
+---
+name: Question
+about: Ask a question about PuffinFlow usage, concepts, or best practices
+title: '[QUESTION] '
+labels: ['question', 'needs-triage']
+assignees: ''
+---
+
+## Question Summary
+
+**What would you like to know?**
+A clear and concise description of your question.
+
+**Category**
+What type of question is this?
+- [ ] Usage/How-to
+- [ ] Best practices
+- [ ] Architecture/Design
+- [ ] Performance
+- [ ] Integration
+- [ ] Troubleshooting
+- [ ] Conceptual understanding
+- [ ] Other (please specify)
+
+## Context
+
+**What are you trying to achieve?**
+Describe your overall goal or use case.
+
+**What have you tried so far?**
+Share any approaches you've attempted or research you've done.
+
+**Code example (if applicable)**
+```python
+# Share relevant code that you're working with
+from puffinflow import Agent
+
+# Your code here
+```
+
+**Current behavior**
+If you have code that's running but not behaving as expected, describe what's happening.
+
+**Expected or desired behavior**
+Describe what you want to happen or what you think should happen.
+
+## Environment Information
+
+**PuffinFlow version:**
+<!-- Run: pip show puffinflow -->
+
+**Python version:**
+<!-- Run: python --version -->
+
+**Operating System:**
+<!-- e.g., Ubuntu 20.04, Windows 10, macOS 12.0 -->
+
+**Optional dependencies:**
+Which optional dependencies do you have installed?
+- [ ] observability
+- [ ] integrations
+- [ ] cli
+- [ ] all
+- [ ] none
+
+## Specific Questions
+
+**Main question:**
+<!-- Your primary question here -->
+
+**Follow-up questions:**
+<!-- Any related questions you have -->
+
+**Documentation references:**
+Have you checked the documentation? If so, which sections?
+- [ ] README
+- [ ] API documentation
+- [ ] Examples
+- [ ] Tutorials
+- [ ] I couldn't find relevant documentation
+
+**Links to documentation you've read:**
+<!-- If you've read specific documentation, link to it here -->
+
+## Additional Context
+
+**Related issues/discussions:**
+<!-- Link any related issues or discussions you've found -->
+
+**External resources:**
+<!-- Any blog posts, Stack Overflow questions, or other resources you've consulted -->
+
+**Screenshots/diagrams:**
+<!-- If visual aids would help explain your question, include them here -->
+
+**Error messages (if any):**
+```
+Paste any error messages here
+```
+
+**Configuration (if relevant):**
+```python
+# Share your configuration if it's relevant to the question
+```
+
+## Community Guidelines
+
+**Research done:**
+- [ ] I have searched existing issues and discussions
+- [ ] I have read the relevant documentation
+- [ ] I have looked at the examples in the repository
+- [ ] I have searched online for similar questions
+
+**Question clarity:**
+- [ ] My question is specific and focused
+- [ ] I have provided sufficient context
+- [ ] I have included relevant code examples
+- [ ] I have specified my environment details
+
+## Help Us Help You
+
+**Response format preference:**
+- [ ] Code example
+- [ ] Detailed explanation
+- [ ] Links to documentation
+- [ ] Step-by-step guide
+- [ ] Conceptual overview
+- [ ] No preference
+
+**Urgency:**
+- [ ] Urgent (blocking my work)
+- [ ] High (important for current project)
+- [ ] Medium (would like to know soon)
+- [ ] Low (general curiosity)
+
+**Follow-up availability:**
+- [ ] Available for follow-up questions
+- [ ] Limited availability for follow-up
+- [ ] Prefer complete answer in first response
+
+## Contribution
+
+**Would you be interested in contributing?**
+If we help you solve this problem, would you be interested in:
+- [ ] Writing documentation to help others with similar questions
+- [ ] Creating an example or tutorial
+- [ ] Improving existing documentation
+- [ ] Contributing code improvements
+- [ ] Just getting my question answered
+
+## Thank You
+
+Thank you for taking the time to ask a thoughtful question! The PuffinFlow community appreciates well-researched questions that help everyone learn.
+
+**Additional notes:**
+<!-- Any other information you think might be helpful -->