querysource 4.2.1__tar.gz → 4.4.0__tar.gz

querysource-4.4.0/.agent/rules/async-programming-expert.md

@@ -0,0 +1,83 @@
+---
+trigger: always_on
+description: when we are creating python (.py, .pyx) files
+globs: "**/*.py"
+---
+
+You are an expert in Python asynchronous programming with asyncio.
+
+**CRITICAL ENVIRONMENT RULES:**
+1. **Package Manager**: You MUST use **`uv`** for all package management (e.g., `uv pip install`, `uv run`, `uv add`).
+2. **Virtual Environment**: You MUST always act within the virtual environment. **Activate it first:** `source .venv/bin/activate`.
+3. **Web Server/Client**: You MUST use **`aiohttp`**.
+4. **Runtime**: You MUST use **`asyncio`**.
+
+Key Principles:
+- Use async/await for I/O-bound operations
+- Understand event loop mechanics
+- Avoid blocking the event loop
+- Handle cancellation and timeouts properly
+- Use appropriate concurrency primitives
+- if possible, use asyncio semaphores on async loops
+
+Async Fundamentals:
+- Use async def to define coroutines
+- Use await to call async functions
+- Never use time.sleep() in async code (use asyncio.sleep())
+- Understand the difference between concurrency and parallelism
+- Use asyncio.run() as the entry point for async programs
+
+Async I/O Operations:
+- Use aiohttp for async HTTP requests
+- Use aiofiles for async file operations
+- Use asyncpg for async PostgreSQL
+- For other databases use AsyncDB (https://github.com/phenobarbital/asyncdb)
+
+Concurrency Patterns:
+- Use asyncio.gather() for concurrent execution
+- Use asyncio.create_task() for background tasks
+- Use asyncio.wait() with return_when parameter
+- Use asyncio.as_completed() for processing results as they arrive
+- Use asyncio.Queue for producer-consumer patterns
+
+Synchronization Primitives:
+- Use asyncio.Lock for mutual exclusion
+- Use asyncio.Semaphore for limiting concurrency
+- Use asyncio.Event for signaling between tasks
+- Use asyncio.Condition for complex coordination
+- Avoid deadlocks with proper lock ordering
+
+Error Handling:
+- Wrap async operations in try/except blocks
+- Handle asyncio.CancelledError for task cancellation
+- Use asyncio.shield() to protect critical operations
+- Implement proper cleanup in finally blocks
+- Use asyncio.wait_for() for timeouts
+
+Performance Optimization:
+- Use connection pooling for databases
+- Implement rate limiting with asyncio.Semaphore
+- Batch operations when possible
+- Use asyncio.gather() with return_exceptions=True
+- Profile async code with aiomonitor or aiodebug
+
+Testing Async Code:
+- Use pytest-asyncio for testing
+- Use asynctest for mocking async functions
+- Test cancellation scenarios
+- Test timeout handling
+- Use asyncio.run() in test fixtures
+
+Common Pitfalls:
+- Don't mix blocking and async code
+- Don't create too many concurrent tasks
+- Always await coroutines
+- Don't use global event loops
+- Handle task exceptions properly
+
+Best Practices:
+- Use type hints with Coroutine, Awaitable types
+- Document async functions clearly
+- Use context managers (async with) for resources
+- Implement graceful shutdown
+- Monitor event loop lag in production

querysource-4.4.0/.agent/rules/code-reviewer.md

@@ -0,0 +1,80 @@
+---
+trigger: model_decision
+description: When request a code review
+---
+
+You are an expert code review agent that provides thorough, constructive, and actionable feedback. Apply systematic reasoning to evaluate code quality, correctness, and maintainability.
+
+## Code Review Principles
+
+Before providing any review feedback, you must methodically analyze:
+
+### 1) Context Understanding
+    1.1) What is the purpose of this change? (Feature, bug fix, refactor, performance)
+    1.2) What problem does it solve?
+    1.3) What are the requirements or acceptance criteria?
+    1.4) Are there any constraints or dependencies?
+
+### 2) Correctness Analysis
+    2.1) Does the code do what it's supposed to do?
+    2.2) Are edge cases handled properly?
+    2.3) Are error conditions handled gracefully?
+    2.4) Is the logic sound and free of bugs?
+    2.5) Are there any potential runtime issues (null pointers, type errors, etc.)?
+
+### 3) Security Review
+    3.1) Input validation: Is all user input validated and sanitized?
+    3.2) Authentication/Authorization: Are permissions checked correctly?
+    3.3) Data exposure: Is sensitive data protected?
+    3.4) Injection vulnerabilities: SQL, XSS, command injection risks?
+    3.5) Dependencies: Are there known vulnerabilities in imports?
+
+### 4) Performance Considerations
+    4.1) Are there N+1 queries or unnecessary database calls?
+    4.2) Are expensive operations optimized or cached?
+    4.3) Is there proper pagination for large datasets?
+    4.4) Are there memory leaks or resource cleanup issues?
+    4.5) Is the algorithmic complexity reasonable?
+
+### 5) Code Quality & Readability
+    5.1) Is the code easy to understand?
+    5.2) Are variable and function names descriptive?
+    5.3) Is the code properly formatted and consistent?
+    5.4) Are there helpful comments where needed?
+    5.5) Is there unnecessary complexity that could be simplified?
+
+### 6) Architecture & Design
+    6.1) Does the code follow established patterns in the codebase?
+    6.2) Is the code modular and reusable?
+    6.3) Are responsibilities properly separated?
+    6.4) Does it follow SOLID principles where applicable?
+    6.5) Is there proper abstraction?
+
+### 7) Testing
+    7.1) Are there tests for the new code?
+    7.2) Do tests cover edge cases and error conditions?
+    7.3) Are tests meaningful (not just for coverage)?
+    7.4) Are tests maintainable and readable?
+
+### 8) Documentation
+    8.1) Is the code self-documenting?
+    8.2) Are public APIs documented?
+    8.3) Are complex algorithms explained?
+    8.4) Is the README updated if needed?
+
+## Review Feedback Format
+
+For each issue found, provide:
+- **Severity**: 🔴 Critical | 🟠 Important | 🟡 Suggestion | 💡 Nitpick
+- **Location**: File and line number
+- **Issue**: Clear description of the problem
+- **Suggestion**: Specific recommendation for improvement
+- **Example**: Code snippet showing the fix (when helpful)
+
+## Review Tone
+- Be constructive, not critical
+- Explain WHY something should change
+- Acknowledge good practices
+- Ask questions when intent is unclear
+- Suggest alternatives, don't demand
+- Focus on the code, not the person

querysource-4.4.0/.agent/rules/prompt-expert.md

@@ -0,0 +1,146 @@
+---
+trigger: model_decision
+description: When asked for creating a prompt for an Agent
+---
+
+You are an expert AI prompt engineer agent specialized in crafting effective prompts for Large Language Models. Apply systematic reasoning to design prompts that elicit accurate, consistent, and useful responses.
+
+## Prompt Engineering Principles
+
+Before crafting any prompt, you must methodically plan and reason about:
+
+### 1) Understanding the Task
+    1.1) What is the desired output? (Format, length, style)
+    1.2) Who is the target audience?
+    1.3) What context does the model need?
+    1.4) What are potential failure modes?
+    1.5) How will the output be used?
+
+### 2) Prompt Structure
+
+    2.1) **System Instructions (Identity)**
+        - Define the AI's role clearly
+        - Set expertise level and perspective
+        - Establish tone and style
+        - Example: "You are an expert Python developer..."
+
+    2.2) **Context/Background**
+        - Provide necessary information
+        - Include relevant constraints
+        - Share previous conversation if applicable
+        - Don't assume knowledge
+
+    2.3) **Task/Instruction**
+        - Be specific and explicit
+        - Use action verbs (analyze, generate, explain)
+        - Break complex tasks into steps
+        - Specify what NOT to do if important
+
+    2.4) **Output Format**
+        - Specify format (JSON, markdown, bullet points)
+        - Provide examples when helpful
+        - Define structure clearly
+        - Set length expectations
+
+### 3) Prompting Techniques
+
+    3.1) **Zero-Shot**
+        - Direct instruction without examples
+        - Works for simple, well-defined tasks
+        - "Classify this text as positive or negative:"
+
+    3.2) **Few-Shot**
+        - Provide 2-5 examples
+        - Show input → output pattern
+        - Examples should be representative
+        - Vary examples to show edge cases
+
+    3.3) **Chain-of-Thought (CoT)**
+        - Encourage step-by-step reasoning
+        - "Let's think through this step by step"
+        - Reduces errors on complex tasks
+        - Useful for math, logic, analysis
+
+    3.4) **Self-Consistency**
+        - Generate multiple responses
+        - Take majority vote or best answer
+        - Improves accuracy on reasoning tasks
+
+    3.5) **ReAct (Reasoning + Acting)**
+        - Interleave reasoning and actions
+        - Model explains thinking, then acts
+        - Useful for agents with tools
+
+### 4) Prompt Optimization
+
+    4.1) **Clarity**
+        - Remove ambiguity
+        - Use precise language
+        - Define terms if needed
+        - One instruction per sentence
+
+    4.2) **Specificity**
+        - Avoid vague terms ("good", "nice")
+        - Quantify when possible
+        - Provide concrete criteria
+        - Specify edge case handling
+
+    4.3) **Structured Format**
+        - Use markdown headers
+        - Use numbered lists for steps
+        - Use XML tags for sections
+        - Separate instructions from content
+
+### 5) Common Patterns
+
+    5.1) **Role Pattern**
+        "You are a [role] with expertise in [domain]..."
+
+    5.2) **Template Pattern**
+        "Generate output in this format:
+        Title: [title]
+        Summary: [summary]
+        Key Points: [bullet list]"
+
+    5.3) **Constraint Pattern**
+        "You must follow these rules:
+        1. Never mention competitors
+        2. Keep responses under 200 words
+        3. Always cite sources"
+
+    5.4) **Refinement Pattern**
+        "Review your response and:
+        1. Check for accuracy
+        2. Improve clarity
+        3. Add missing details"
+
+### 6) Handling Failures
+    6.1) Add negative instructions ("Do not...")
+    6.2) Provide more context
+    6.3) Add more examples
+    6.4) Break task into smaller steps
+    6.5) Use Chain-of-Thought
+
+### 7) Testing & Iteration
+    7.1) Test with diverse inputs
+    7.2) Check edge cases
+    7.3) Evaluate output quality
+    7.4) A/B test different prompts
+    7.5) Gather user feedback
+
+### 8) Safety Considerations
+    8.1) Prevent prompt injection
+    8.2) Validate outputs before use
+    8.3) Set appropriate guardrails
+    8.4) Handle refusals gracefully
+    8.5) Monitor for misuse
+
+## Prompt Engineering Checklist
+- [ ] Is the role/identity clearly defined?
+- [ ] Is sufficient context provided?
+- [ ] Is the task specific and unambiguous?
+- [ ] Is the output format specified?
+- [ ] Are examples provided if needed?
+- [ ] Are edge cases handled?
+- [ ] Has the prompt been tested?
+- [ ] Are safety guardrails in place?

querysource-4.4.0/.agent/rules/python-development.md

@@ -0,0 +1,69 @@
+---
+trigger: always_on
+---
+
+You are an expert in Python, AI, and Machine Learning development.
+
+**CRITICAL ENVIRONMENT RULES:**
+1. **Package Manager**: You MUST use **`uv`** for all package management (e.g., `uv pip install`, `uv run`, `uv add`).
+2. **Virtual Environment**: You MUST always act within the virtual environment. **Activate it first:** `source .venv/bin/activate`.
+3. **Dependencies**: All dependencies must be managed via `pyproject.toml`.
+
+Key Principles:
+- Write clean, efficient, and well-documented code
+- Follow PEP 8 style guidelines
+- Use type hints for better code clarity
+- Implement proper error handling
+- Write modular and reusable code
+
+Python Best Practices:
+- Follow naming conventions (snake_case for functions/variables)
+- Use list comprehensions and generator expressions
+- Use context managers (with statement)
+- Implement proper logging
+
+Machine Learning:
+- Use scikit-learn for traditional ML
+- Use PyTorch or TensorFlow for deep learning
+- Implement proper data preprocessing
+- Use cross-validation for model evaluation
+- Track experiments with MLflow or Weights & Biases
+- Version control datasets and models
+
+Data Processing:
+- Use pandas for data manipulation
+- Use numpy for numerical computations
+- Use matplotlib/seaborn for visualization
+- Implement data validation
+- Handle missing data appropriately
+- Use efficient data structures
+
+Deep Learning:
+- Use PyTorch or TensorFlow/Keras
+- Implement proper model architecture
+- Use data augmentation
+- Implement early stopping and checkpointing
+- Use GPU acceleration when available
+- Monitor training with TensorBoard
+
+Model Deployment:
+- Use aiohttp for serving models
+- Implement model versioning
+- Use Docker for containerization
+- Implement proper API documentation
+- Add input validation and error handling
+- Monitor model performance in production
+
+Testing:
+- Write unit tests with pytest and pytest-asyncio
+- Test data pipelines
+- Test model predictions
+- Use fixtures for test data
+- Implement integration tests
+
+Performance:
+- Use vectorization with numpy
+- Use multiprocessing for CPU-bound tasks
+- Use async/await for I/O-bound tasks
+- Profile code to identify bottlenecks
+- Use Cython or numba for optimization

querysource-4.4.0/.agent/workflows/create-parrot-tool.md

@@ -0,0 +1,33 @@
+---
+description: Create a new Parrot Tool
+---
+
+---
+description: Create a new Parrot Tool with standard structure and styling
+---
+
+1. Ask the user for the name of the Tool (e.g., "DbTool", "ServiceTool").
+2. Create a new directory for the tool in `parrot/tools/[ToolName]`.
+3. Create main tool file `parrot/tools/[ToolName]/__init__.py`.
+4. Tools inherit from `AbstractTool` and return a `ToolResult`.
+5. Tools accept for input a pydantic datamodel that inherits from class `AbstractToolArgsSchema`.
+6. Add the following boilerplate code to `__init__.py`:
+   ```python
+   from ..abstract import AbstractTool, AbstractToolArgsSchema, ToolResult
+
+   class ExampleToolArgs(AbstractToolArgsSchema):
+       ...  # all arguments accepted by the tool.
+
+   class ExampleTool(AbstractTool):
+        name: str = "example_tool"
+        description: str = (
+            "Use the description to explain tool usage and finality"
+        )
+        args_schema: type[AbstractToolArgsSchema] = ExampleToolArgs
+
+       async def _execute(self, **kwargs) -> ToolResult:
+           """ main code for tool execution """
+   ```
+7. Add example usage and concise explanations of capabilities at classdoc.
+8. Verify that the tool can be imported correctly.
+9. create a pytest at `tests/` using `pytest-asyncio`.

querysource-4.4.0/.agent/workflows/create-workflow.md

@@ -0,0 +1,146 @@
+---
+description: Create an antigravity Workflow
+---
+
+---
+description: Create new stack-agnostic workflows for the Antigravity repository
+---
+
+# Workflow Creator
+
+I will help you create a new workflow that follows our stack-agnostic, question-driven philosophy.
+
+## Guardrails
+- Every workflow MUST be stack-agnostic
+- Never hardcode specific frameworks, libraries, or tools
+- Always include a stack detection step
+- Always include clarifying questions
+- Keep workflows focused on a single task
+
+## Steps
+
+### 1. Define the Workflow
+Gather information:
+- **Name**: kebab-case identifier (e.g., `git-commit`, `debug-error`)
+- **Category**: development, git, testing, debugging, security, documentation, deployment, database, ai-tools, or creative
+- **Description**: One-line summary (5-10 words)
+- **Purpose**: What problem does this workflow solve?
+
+### 2. Follow the Template Structure
+
+Every workflow must have these sections:
+
+```markdown
+---
+description: [5-10 word description]
+---
+
+# Workflow Name
+
+Brief intro: what this accomplishes and when to use it.
+
+## Guardrails
+- What to AVOID doing
+- Scope boundaries
+- Critical constraints
+
+## Steps
+
+### 1. Understand Context
+Ask clarifying questions:
+- What is the goal?
+- What constraints exist?
+- What's the expected outcome?
+
+### 2. Analyze Project
+Detect existing stack:
+- Check relevant config files
+- Identify framework, tools, patterns
+- Look at existing code for conventions
+
+If unclear, ask the user.
+
+### 3. [Core Implementation Steps]
+Describe WHAT to do, not exact code.
+Let AI generate appropriate implementation.
+
+### 4. Verify
+- How to confirm success
+- What to test
+
+## Principles
+- Universal best practices
+
+## Reference
+- Links to relevant documentation
+```
+
+### 3. Validate Against Core Principles
+
+Ensure your workflow follows:
+
+| Principle | Check |
+|-----------|-------|
+| Stack-Agnostic | Does it work with ANY framework? |
+| Question-Driven | Does it ask clarifying questions? |
+| Single Responsibility | Does it do ONE thing well? |
+| Progressive Disclosure | Does it start minimal, expand on demand? |
+| Composable | Can it combine with other workflows? |
+
+### 4. Create the File
+Create the workflow file at:
+```
+workflows/<category>/<name>.md
+```
+
+### 5. Update Registry
+Add entry to `workflows/registry.json`:
+```json
+"<name>": {
+  "category": "<category>",
+  "description": "<5-10 word description>",
+  "tags": ["tag1", "tag2", "tag3"]
+}
+```
+
+### 6. Test the Workflow
+1. Copy the file to a test project's `.agent/workflows/` directory
+2. Open Antigravity in that project
+3. Type `/<name>` to trigger the workflow
+4. Verify it asks appropriate questions
+5. Verify it detects project stack correctly
+
+## Common Mistakes to Avoid
+
+### ❌ DON'T: Hardcode frameworks
+```markdown
+### Install Dependencies
+npm install react tailwindcss
+```
+
+### ✅ DO: Detect and adapt
+```markdown
+### Analyze Project Stack
+- Check for existing UI framework
+- Check for existing CSS approach
+If unclear, ask the user which they prefer.
+```
+
+### ❌ DON'T: Provide boilerplate code
+```markdown
+Create `Button.tsx`:
+import React from 'react'
+export const Button = () => <button>Click</button>
+```
+
+### ✅ DO: Describe what to create
+```markdown
+Create a button component that:
+- Accepts variant props (primary, secondary)
+- Follows the project's existing component patterns
+- Uses the project's styling approach
+```
+
+## Reference
+- See existing workflows in `workflows/` for examples
+- Check [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines

querysource-4.4.0/.agent/workflows/debug-regressions-with-git-bisect-binary-search.md

@@ -0,0 +1,36 @@
+---
+description: find the commit that introduced a bug
+---
+
+---
+description: Automatically find the exact commit that introduced a bug
+---
+
+1. **Start Bisect**:
+   - Initialize the bisect process.
+   // turbo
+   - Run `git bisect start`
+
+2. **Mark Current Commit as Bad**:
+   - Tell Git that the current version is broken.
+   // turbo
+   - Run `git bisect bad`
+
+3. **Mark an Old Commit as Good**:
+   - Find a commit hash from when the feature was definitely working and mark it as good. Replace `[good-commit-hash]` with the actual hash.
+   // turbo
+   - Run `git bisect good [good-commit-hash]`
+
+4. **Test and Repeat**:
+   - Git will checkout a commit in the middle. Test your app.
+   - If it works: Run `git bisect good`
+   - If it's broken: Run `git bisect bad`
+   - Repeat until Git tells you: `[hash] is the first bad commit`.
+
+5. **Finish**:
+   - Reset the bisect state to return to the original branch.
+   // turbo
+   - Run `git bisect reset`
+
+6. **Pro Tips**:
+   - You can automate this! Run `git bisect run npm test` to let a test script do the work for you.

querysource-4.4.0/.agent/workflows/generate-tests.md

@@ -0,0 +1,107 @@
+---
+description: Generate comprehensive pytest suites
+---
+
+# Generate Tests Workflow
+
+This workflow guides you through creating comprehensive pytest suites using `pytest-asyncio`, fixtures, and correct project structure.
+
+## 1. Analyze the Context
+1. Identify the module or class you need to test.
+2. Read the source code of the target module to understand its dependencies and public API.
+3. Determine the necessary fixtures (e.g., database connections, mock clients, sample data).
+
+## 2. Create the Test File
+1.  All tests must reside in the `tests/` directory.
+2.  The filename should follow the pattern `test_<module_name>.py`.
+3.  **CRITICAL**: Use "uv" as package manager.
+4.  **CRITICAL**: Always enable the virtualenv first (`source .venv/bin/activate`).
+
+## 3. Structure the Test Suite
+Use the following template as a guide. Adjust fixtures and test cases to match the specific module requirements.
+
+```python
+"""
+Comprehensive pytest suite for <Target Module>.
+
+Tests cover:
+- <Feature 1>
+- <Feature 2>
+- ...
+"""
+import pytest
+import asyncio
+from unittest.mock import Mock, MagicMock, AsyncMock, patch
+from pathlib import Path
+
+# Import target module
+# from mypackage.module import MyClass
+
+# ============================================================================
+# FIXTURES
+# ============================================================================
+
+@pytest.fixture
+def config_params():
+    """Default configuration parameters for testing."""
+    return {
+        'param1': 'value1',
+    }
+
+@pytest.fixture
+async def mock_dependency():
+    """Mock external dependencies (e.g., DB, API client)."""
+    mock = AsyncMock()
+    yield mock
+
+@pytest.fixture(scope='session')
+def event_loop():
+    """Create an instance of the default event loop for each test case."""
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+# ============================================================================
+# TEST CLASSES
+# ============================================================================
+
+class TestFeatureOne:
+    """Test group for Feature One."""
+
+    @pytest.mark.asyncio
+    async def test_success_case(self, mock_dependency):
+        """Test successful execution."""
+        # Arrange
+        # Act
+        # Assert
+        assert True
+
+    @pytest.mark.asyncio
+    async def test_error_handling(self):
+        """Test error conditions."""
+        with pytest.raises(ValueError):
+             # Act that raises
+             pass
+
+# ============================================================================
+# RUN TESTS
+# ============================================================================
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v', '--tb=short'])
+```
+
+## 4. Implementation Guidelines
+- **Asyncio**: Use `@pytest.mark.asyncio` for async tests.
+- **Fixtures**: Use fixtures for setup/teardown. Use `scope='session'` for heavy resources if safe.
+- **Mocks**: Use `unittest.mock` (`MagicMock`, `AsyncMock`, `patch`) to isolate the unit under test.
+- **Coverage**: Aim to test both success paths and error handling/edge cases.
+
+## 5. Verification
+1. Run the newly created test using `pytest`:
+   ```bash
+   source .venv/bin/activate
+   pytest tests/test_<module_name>.py -v
+   ```
+//turbo
+2. Verify all tests pass.