agent-rules-kit

--- globs: <root>/**/* alwaysApply: false --- # Pampa Implementation Guide ## Installation & Setup ### Quick Start Pampa is designed to be simple - just install and start using it immediately. ```bash # Install Pampa globally npm install -g pampa # Or use directly with npx npx pampa index ``` ### Project Setup Initialize Pampa in your project: ```bash # Navigate to your project root cd your-project # Index your codebase (this creates .pampa/ directory) pampa index # Start searching pampa search "authentication function" ``` ### Configuration (Optional) Pampa works out of the box, but you can customize it with a `pampa.yml` file: ```yaml # pampa.yml (optional) provider: auto # auto, openai, transformers, ollama, cohere exclude: - node_modules/ - .git/ - dist/ - build/ include: - '**/*.py' - '**/*.ts' - '**/*.js' - '**/*.java' - '**/*.go' - '**/*.php' - '**/*.rb' - '**/*.cpp' - '**/*.c' - '**/*.h' ``` ## Core Commands ### Indexing ```bash # Index the entire project pampa index # Index with specific provider pampa index --provider openai # Update existing index pampa update # Check index statistics pampa stats ``` ### Searching ```bash # Basic semantic search pampa search "user authentication" # Search with limit pampa search "database connection" --limit 5 # Search in specific language pampa search "error handling" --language python ``` ### MCP Integration Pampa provides built-in MCP server functionality: ```bash # Start MCP server pampa mcp-server # Start with custom port pampa mcp-server --port 8080 # Start with specific provider pampa mcp-server --provider openai ``` ## AI Agent Usage Patterns ### Finding Code Examples ```bash # Find authentication implementations pampa search "user login authentication" # Find database queries pampa search "SELECT query with JOIN" # Find error handling patterns pampa search "try catch exception handling" ``` ### Understanding Code Structure ```bash # Find main entry points pampa search "main function application start" # Find configuration files pampa search "config settings environment" # Find API endpoints pampa search "REST API routes endpoints" ``` ### Pattern Discovery ```bash # Find design patterns pampa search "factory pattern implementation" # Find architectural patterns pampa search "MVC controller pattern" # Find testing patterns pampa search "unit test mock examples" ``` ## API Usage (For MCP Integration) ### Search Code ```javascript // Using Pampa MCP client const results = await client.callTool('pampa_search_code', { query: 'authentication function', limit: 10, }); ``` ### Get Code Chunk ```javascript // Get specific code chunk by SHA const chunk = await client.callTool('pampa_get_code_chunk', { sha: 'abc123...', }); ``` ### Project Statistics ```javascript // Get project indexing stats const stats = await client.callTool('pampa_get_project_stats', { path: '.', }); ``` ## Best Practices for AI Agents ### Effective Query Strategies 1. **Be Specific**: Use concrete terms about functionality - Good: "JWT token validation function" - Avoid: "auth stuff" 2. **Include Context**: Mention the technology or pattern - Good: "React useState hook examples" - Avoid: "state management" 3. **Use Intent-Based Queries**: Describe what you want to accomplish - Good: "validate email address format" - Avoid: "email function" ### Search Refinement ```bash # Start broad, then narrow down pampa search "database" # Too broad pampa search "database connection" # Better pampa search "PostgreSQL connection pool" # Most specific ``` ### Code Understanding Workflow 1. **Overview**: Search for main concepts first 2. **Details**: Drill down into specific implementations 3. **Context**: Find related code and dependencies 4. **Examples**: Look for usage patterns and tests ## Integration with Development Tools ### IDE Integration Pampa works well with: - VS Code (via MCP) - Cursor (native support) - Any editor with MCP support ### CI/CD Integration ```yaml # .github/workflows/pampa-index.yml name: Update Pampa Index on: push: branches: [main] jobs: index: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Pampa run: npm install -g pampa - name: Update Index run: pampa update ``` ### Docker Integration ```dockerfile # Dockerfile FROM node:18 RUN npm install -g pampa COPY . /app WORKDIR /app RUN pampa index ``` ## Troubleshooting ### Common Issues 1. **Slow Indexing**: Large codebases may take time on first index - Solution: Use `.pampaignore` to exclude unnecessary files 2. **Memory Usage**: High memory usage with large projects - Solution: Index incrementally or use smaller chunks 3. **No Results**: Search returns empty results - Solution: Ensure project is indexed, try broader queries ### Performance Optimization ```bash # Check index size and status pampa stats # Re-index if corruption suspected rm -rf .pampa/ pampa index # Update index incrementally pampa update ``` ## Advanced Usage ### Custom Providers Configure different embedding providers: ```yaml # pampa.yml provider: openai openai: api_key: your-api-key model: text-embedding-3-small ``` ### Batch Operations ```bash # Search multiple queries pampa search "auth" "database" "validation" --batch # Export search results pampa search "API endpoints" --output results.json ``` This implementation guide provides everything needed to effectively use Pampa for semantic code search and AI agent integration.