### Sample Prompt: Understanding Project Structure

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `get_project_stats()` function to explore the codebase structure.

```text
🔍 "Let me explore this codebase structure"
→ get_project_stats()
```

--------------------------------

### Index Project for First-Time Setup

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Initializes the project index by creating a `.pampa/` directory containing the database and code chunks. Accepts the directory path to index and an optional embedding provider.

```python
index_project(path=".", provider="auto")
```

--------------------------------

### Scoped Search Examples in JavaScript

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Demonstrates various ways to perform scoped searches using the `search_code` function. This includes searching within specific file paths, filtering by programming language, and using tags for more precise results. It also shows how to combine multiple scoping criteria.

```javascript
// Search only in service layer
search_code('payment processing', { path_glob: ['app/Services/**'] });

// Search PHP backend only
search_code('user authentication', { lang: ['php'] });

// Search with tags
search_code('create session', { tags: ['stripe', 'payment'] });

// Combine multiple scopes
search_code('validation', {
	path_glob: ['app/Http/**'],
	lang: ['php'],
	tags: ['api'],
});
```

--------------------------------

### Clone and Setup PAMPA Repository

Source: https://github.com/tecnomanu/pampa/blob/master/docs/CONTRIBUTING.md

Steps to clone the PAMPA repository and install its dependencies using npm. This is a prerequisite for local development.

```bash
git clone https://github.com/your-username/pampa.git
cd pampa
npm install
```

--------------------------------

### Sample Prompt: Enable Hybrid Search

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt demonstrating how to enable hybrid search for potentially better recall, specifying the `reranker`.

```text
🆕 "Get better results with hybrid search"
→ search_code("checkout flow", hybrid="on", reranker="transformers")
```

--------------------------------

### Sample Prompt: Verify New Function Indexing

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using `search_code()` to verify if a newly added function has been successfully indexed.

```text
🔍 "Verify my new function was indexed"
→ search_code("your new function name")
```

--------------------------------

### Project Statistics JSON Example

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

An example JSON structure representing project statistics, including total function count, detected languages, and file distribution by language.

```json
{
	"total_functions": 150, 
	"languages": ["javascript", "python"], 
	"files_by_language": {
		"javascript": 45,
		"python": 12
	}
}
```

--------------------------------

### Sample Prompt: Update Project Index

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt to update the project index after making code changes.

```text
🔄 "Update the project index with my changes"
→ update_project()
```

--------------------------------

### Sample Prompt: Check Integration with Existing Code

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using `search_code()` to check how a new function or feature integrates with existing code.

```text
🔍 "Check integration with existing code"
→ search_code("related functionality")
```

--------------------------------

### Sample Prompt: Use Context Pack for Domain Focus

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt showing how to use a context pack to focus searches on a specific domain, followed by a targeted search query.

```text
🆕 "Use context packs for domain focus"
→ use_context_pack("stripe-backend")
→ search_code("create payment session")  // Now scoped to Stripe backend
```

--------------------------------

### Sample Prompt: Search for Main Application Logic

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to find the main application entry point.

```text
🔍 "Show me the main application logic"
→ search_code("main application entry point")
```

--------------------------------

### Sample Prompt: Scoped Search by Path Glob

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt demonstrating a scoped search using `path_glob` to search only within specific directories.

```text
🆕 "Focus search on specific directories"
→ search_code("payment processing", path_glob=["app/Services/**"])
```

--------------------------------

### Get Project Statistics Overview

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Retrieves a summary of the project's statistics, including file counts, detected programming languages, and function statistics. Requires the directory path to analyze.

```python
get_project_stats(path=".")
```

--------------------------------

### Project Indexing API

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

APIs for initializing and updating the project index. `index_project` is used for the first-time setup, while `update_project` should be used frequently after code changes.

```APIDOC
## POST /index_project

### Description
Creates the initial project index, including a `.pampa/` directory with database and code chunks.

### Method
POST

### Endpoint
/index_project

### Parameters
#### Query Parameters
- **path** (string) - Optional - Directory to index. Defaults to the current directory.
- **provider** (string) - Optional - Embedding provider to use (e.g., 'auto', 'openai', 'transformers', 'ollama', 'cohere'). Defaults to 'auto'.

### Request Example
```json
{
  "path": ".",
  "provider": "auto"
}
```

### Response
#### Success Response (200)
Indicates that the project indexing has started or completed.

#### Response Example
```json
{
  "message": "Project indexing initiated."
}
```

## POST /update_project

### Description
Updates the project index to reflect recent code changes. It adds new functions, removes deleted ones, and updates modified code.

### Method
POST

### Endpoint
/update_project

### Parameters
#### Query Parameters
- **path** (string) - Optional - Directory to update. Defaults to the current directory.
- **provider** (string) - Optional - Embedding provider to use. Defaults to 'auto'.

### Request Example
```json
{
  "path": ".",
  "provider": "auto"
}
```

### Response
#### Success Response (200)
Indicates that the project index update has started or completed.

#### Response Example
```json
{
  "message": "Project index updated."
}
```
```

--------------------------------

### Sample Prompt: Search for Authentication Functions

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to find authentication and security-related functions.

```text
🔍 "Find authentication and security functions"
→ search_code("authentication security login")
```

--------------------------------

### Sample Prompt: Understand Error Handling

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to understand how error handling is implemented in the project.

```text
🔍 "How is error handling implemented?"
→ search_code("error handling exception handling")
```

--------------------------------

### Install Pampa CLI

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Installs the latest version of the Pampa command-line interface globally. This command is used to upgrade the Pampa tools to the newest release.

```bash
npm install -g pampa@latest
```

--------------------------------

### Sample Prompt: Find API Endpoints

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to identify existing API endpoints.

```text
🔍 "Are there existing API endpoints?"
→ search_code("API endpoint route handler")
```

--------------------------------

### Sample Prompt: Find Similar Functions During Development

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to find functions similar to the one currently being developed.

```text
🔍 "Find functions similar to what I'm building"
→ search_code("description of your planned function")
```

--------------------------------

### Sample Prompt: Check Utility Functions

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to check for existing utility or helper functions.

```text
🔍 "Check existing utility functions"
→ search_code("utility helper functions")
```

--------------------------------

### Sample Prompt: Look for Validation Patterns

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to find validation patterns within the codebase.

```text
🔍 "Look for validation patterns"
→ search_code("validation pattern schema")
```

--------------------------------

### Sample Prompt: Search for Database Operations

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to find database operations within the project.

```text
🔍 "What database operations exist?"
→ search_code("database query CRUD operations")
```

--------------------------------

### Sample Prompt: Scoped Search by Language

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt demonstrating a scoped search using the `lang` parameter to search only within a specific programming language.

```text
🆕 "Search only backend PHP code"
→ search_code("user authentication", lang=["php"])
```

--------------------------------

### Index Example Project with PAMPA CLI

Source: https://github.com/tecnomanu/pampa/blob/master/docs/CONTRIBUTING.md

Command to index an example project using the PAMPA CLI. This is useful for testing indexing functionality.

```bash
npx pampa index example/
```

--------------------------------

### PAMPA Tool: use_context_pack

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Documentation for the `use_context_pack` tool, which activates predefined search scopes or context packs for focused semantic searching.

```APIDOC
## POST /tools/use_context_pack

### Description
Activates a predefined context pack or search scope within PAMPA. This allows for more targeted semantic searches by focusing on specific areas or functionalities of the project.

### Method
POST

### Endpoint
`/tools/use_context_pack`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the context pack or search scope to activate.
- **path** (string) - Required - The file path to the project root directory where the context pack should be applied.

### Request Example
```json
{
  "name": "api_endpoints_context",
  "path": "/path/to/your/project"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating that the specified context pack has been activated.
```

--------------------------------

### System Instructions Update (Markdown)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Provides an example of how to update system instructions for AI agents using PAMPA v1.12. It contrasts the old search syntax with the new scoped search syntax, emphasizing the use of `lang` and `path_glob` parameters.

```markdown
# Before

search_code("authentication")

# After - Use scoped search

search_code("authentication", { lang: ["php"], path_glob: ["app/**"] })
```

--------------------------------

### PAMPA Examples: React Project

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Practical examples of using PAMPA commands with a React project, including indexing, searching for components, and watching for changes during development.

```bash
# Index React project
pampa index --directory /path/to/react-app --provider openai

# Search components
pampa search "user authentication" --directory /path/to/react-app --lang tsx

# Watch changes during development
pampa watch --directory /path/to/react-app --debounce 1000
```

--------------------------------

### Reinstall PAMPA (Bash)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Command-line instructions for developers to uninstall the current version of PAMPA and install the latest version (v1.12) globally using npm.

```bash
npm uninstall -g pampa
npm install -g pampa@latest
```

--------------------------------

### Sample Prompt: Check for User Validation

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

A sample prompt using Pampa's `search_code()` function to check if the project has user validation mechanisms.

```text
🔍 "Does this project have user validation?"
→ search_code("user validation input validation")
```

--------------------------------

### Watch Changes with PAMPA

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Demonstrates how to watch for file changes in a project using PAMPA, with examples of traditional and new explicit project directory specification.

```bash
# Traditional way
pampa watch /path/to/project

# New clearer options
pampa watch --project /path/to/project
pampa watch --directory /path/to/project
```

--------------------------------

### Context Packs Workflow in JavaScript

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Illustrates the workflow for activating and using domain-specific context packs. After activating a pack (e.g., 'stripe-backend'), all subsequent searches are automatically scoped to that context, ensuring more relevant results for specific domains.

```javascript
// 1. Activate domain-specific context
use_context_pack('stripe-backend');

// 2. All searches now automatically scoped
search_code('create payment'); // → Only Stripe backend results
search_code('handle webhook'); // → Only Stripe webhook handlers
search_code('refund transaction'); // → Only Stripe refund logic
```

--------------------------------

### PAMPA Tool: index_project

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Documentation for the `index_project` tool, used to perform the initial indexing of a project's codebase for PAMPA's memory system.

```APIDOC
## POST /tools/index_project

### Description
Initiates the indexing process for a given project path. This tool analyzes the codebase and creates a searchable index for PAMPA's memory system.

### Method
POST

### Endpoint
`/tools/index_project`

### Parameters
#### Request Body
- **path** (string) - Required - The file path to the project root directory to be indexed.
- **provider** (string) - Optional - Specifies the embedding provider to use (e.g., "auto", "openai", "transformers"). Defaults to "auto" if not provided.

### Request Example
```json
{
  "path": "/path/to/your/project",
  "provider": "openai"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating that the project indexing has started or completed.
```

--------------------------------

### PAMPA Examples: Laravel Project

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Practical examples of using PAMPA commands with a Laravel project, including indexing, searching with language filters, and updating.

```bash
# Index the Laravel project
pampa index --project /path/to/laravel-project --provider transformers

# Search for payment-related functions
pampa search "payment processing" --project /path/to/laravel-project --lang php

# Search in specific services
pampa search "create policy" --project /path/to/laravel-project --path_glob "app/Services/**"

# Update after changes
pampa update --project /path/to/laravel-project
```

--------------------------------

### Phase 1 Upgrade Steps (Bash)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

The initial phase of the recommended upgrade path for PAMPA v1.12, involving global installation, re-indexing projects, and basic functional testing.

```bash
1. npm install -g pampa@latest
2. pampa update  # Re-index existing projects
3. Test basic search functionality
```

--------------------------------

### Chunk Encryption Setup (Bash)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Illustrates the command-line steps to enable at-rest encryption for code chunks in PAMPA v1.12. This requires setting an environment variable for the encryption key before indexing.

```bash
# Enable encryption
export PAMPA_ENCRYPTION_KEY="your-32-byte-key"
pampa index --encrypt on
```

--------------------------------

### Essential AI Agent Session Workflow with PAMPA

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

This sequence outlines the critical steps an AI agent should perform at the beginning of every session using PAMPA. It includes checking project indexing status, syncing changes, and performing an initial search to understand the project context.

```shell
1. get_project_stats() → Check if project is indexed
2. update_project() → Sync with recent changes
3. search_code("main functionality") → Understand project structure
```

--------------------------------

### Update Index with PAMPA

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Shows how to update the project index using PAMPA, including examples of both traditional and new explicit project directory specification.

```bash
# Traditional way
pampa update /path/to/project

# New clearer options
pampa update --project /path/to/project
pampa update --directory /path/to/project
```

--------------------------------

### Context Pack Activation (JavaScript)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Provides an example of how to activate a context pack in PAMPA v1.12 using the `use_context_pack` function. Once activated, subsequent searches are automatically scoped according to the pack's configuration.

```javascript
// Activate a context pack
use_context_pack('stripe-backend');

// All subsequent searches are scoped
search_code('create payment'); // Automatically filtered to Stripe backend
```

--------------------------------

### JavaScript Test Structure Example

Source: https://github.com/tecnomanu/pampa/blob/master/docs/CONTRIBUTING.md

An example structure for a JavaScript test file using ES modules and `child_process.spawn`. It demonstrates setting up test cases and an asynchronous testing function.

```javascript
// test/test-your-feature.js
#!/usr/bin/env node

import { spawn } from 'child_process';

const testCases = [
    {
        name: "Valid input",
        input: { /* test data */ },
        shouldPass: true
    },
    // ... more test cases
];

async function testYourFeature() {
    console.log('🧪 Testing your feature...\n');

    for (const testCase of testCases) {
        // Test implementation
    }
}

if (process.argv[1] && process.argv[1].endsWith('test-your-feature.js')) {
    testYourFeature().catch(console.error);
}
```

--------------------------------

### Install Pampa CLI Globally

Source: https://github.com/tecnomanu/pampa/blob/master/README.md

Commands to install the Pampa CLI globally using npm. This requires Node.js version 20 or higher.

```bash
# Run without installing
npx pampa --help

# Or install globally (requires Node.js 20+)
npm install -g pampa
```

--------------------------------

### PAMPA MCP Usage Rule for AI Agents

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

System instructions for AI agents detailing how to interact with PAMPA for code indexing, searching, and project memory management.

```APIDOC
## PAMPA MCP Usage Rule

### Description
This rule outlines the essential workflow for AI agents using PAMPA as their code memory system. It covers session initialization, code searching strategies, and development best practices to leverage PAMPA effectively.

### Method
N/A (System Instruction)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Core Instructions

#### 1. Session Initialization (ALWAYS at the start of a session):
   - `get_project_stats()`: Checks if the project is indexed.
   - `index_project()`: Indexes the project if no database exists.
   - `update_project()`: Synchronizes the index with recent changes.

#### 2. Before Creating Any Function:
   - `search_code(query, ...)`: Use semantic queries (e.g., "user authentication", "validate email") to find relevant existing code.
   - `get_code_chunk(sha, path)`: Review existing code snippets before writing new code.

#### 3. After Modifying Code:
   - `update_project()`: Updates the project memory with recent changes.

### Available Tools

- `search_code(query, limit, path, ...filters)`: Advanced semantic search with scoping.
- `get_code_chunk(sha, path)`: Retrieves a complete code chunk by its SHA and path.
- `index_project(path, provider)`: Indexes a project for the first time.
- `update_project(path, provider)`: Updates the project index after code changes.
- `get_project_stats(path)`: Retrieves statistics about the indexed project.
- `use_context_pack(name, path)`: Activates predefined search scopes.
```

--------------------------------

### PAMPA MCP Usage Rule for AI Agents

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

This markdown rule provides AI agents with instructions on how to interact with PAMPA for project memory. It covers session start-up procedures, pre-function creation search strategies, and post-modification updates.

```markdown
# PAMPA MCP Usage Rule

You have access to PAMPA, a code memory system that indexes and allows semantic search in projects.

## Basic Instructions

1. **ALWAYS at the start of a session:**

    - Run `get_project_stats` to check if the project is indexed
    - If no database exists, run `index_project`
    - Run `update_project` to sync with recent changes

2. **BEFORE creating any function:**

    - Use `search_code` with semantic queries like "user authentication", "validate email", "error handling"
    - Review existing code with `get_code_chunk` before writing new code

3. **AFTER modifying code:**
    - Run `update_project` to update the knowledge base
    - This keeps the project memory synchronized

## Available Tools

-   `search_code(query, limit, path, filters...)` - 🆕 Advanced semantic search with scoping
-   `get_code_chunk(sha, path)` - Get complete code of a chunk
-   `index_project(path, provider)` - Index project for the first time
-   `update_project(path, provider)` - Update index after changes
-   `get_project_stats(path)` - Get project statistics
-   `use_context_pack(name, path)` - 🆕 Activate predefined search scopes

## Strategy

Use PAMPA as your project memory. Search before creating, keep updated after changes, and leverage existing knowledge to avoid code duplication.
```

--------------------------------

### Create Context Pack (JSON)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

An example JSON configuration file for creating a custom context pack in PAMPA v1.12. This defines a 'Backend Services' pack with specific path glob patterns, languages, and search configurations like hybrid search and reranker.

```json
// .pampa/contextpacks/backend.json
{
	"name": "Backend Services",
	"path_glob": ["app/Services/**", "app/Http/**"],
	"lang": ["php"],
	"hybrid": "on",
	"reranker": "transformers"
}
```

--------------------------------

### Index Project with PAMPA

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Demonstrates how to index a project using PAMPA, showing both traditional and new explicit methods for specifying the project directory.

```bash
# Traditional way
pampa index /path/to/project

# New clearer options
pampa index --project /path/to/project
pampa index --directory /path/to/project
```

--------------------------------

### PAMPA Tool: get_project_stats

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Documentation for the `get_project_stats` tool, which retrieves statistics and information about the indexed project.

```APIDOC
## GET /tools/get_project_stats

### Description
Retrieves statistical information about the currently indexed project, such as the number of files indexed, total lines of code, and indexing status.

### Method
GET

### Endpoint
`/tools/get_project_stats`

### Parameters
#### Query Parameters
- **path** (string) - Required - The file path to the project root directory for which to get statistics.

### Request Example
```
GET /tools/get_project_stats?path=/path/to/your/project
```

### Response
#### Success Response (200)
- **stats** (object) - An object containing project statistics.
  - **indexed_files** (integer) - The number of files indexed.
  - **total_lines** (integer) - The total number of lines of code indexed.
  - **indexing_status** (string) - The current status of the project indexing (e.g., "indexed", "not_indexed").
```

--------------------------------

### PAMPA MCP Configuration

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Configuration snippet to be added to MCP (Multi-Chat Protocol) for integrating PAMPA as a project memory server.

```APIDOC
## POST /configure/mcp

### Description
This endpoint allows you to configure your MCP (Multi-Chat Protocol) to include PAMPA as a project memory server. This enables AI agents to automatically index and semantically search project code.

### Method
POST

### Endpoint
`/configure/mcp`

### Parameters
#### Request Body
- **mcpServers** (object) - Required - A configuration object for MCP servers.
  - **pampa** (object) - Required - Configuration for the PAMPA server.
    - **command** (string) - Required - The command to execute PAMPA (e.g., "npx").
    - **args** (array) - Required - Arguments for the command (e.g., ["-y", "pampa", "mcp"]).
    - **env** (object) - Optional - Environment variables for the PAMPA process.
      - **OPENAI_API_KEY** (string) - Optional - OpenAI API key for embedding models.
```

--------------------------------

### PAMPA Tool: search_code

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Documentation for the `search_code` tool, detailing its purpose, parameters, and advanced filtering capabilities for semantic code search.

```APIDOC
## POST /tools/search_code

### Description
Performs an advanced semantic search across the project's indexed code. This tool allows for natural language queries and supports various filters for precise code retrieval.

### Method
POST

### Endpoint
`/tools/search_code`

### Parameters
#### Query Parameters
- **query** (string) - Required - The natural language query describing the code to search for (e.g., "user validation", "error handling").
- **limit** (integer) - Optional - The maximum number of search results to return (default: 10).
- **path** (string) - Optional - The root directory of the project to search within (default: ".").
- **path_glob** (string) - Optional - Filters results to files matching a glob pattern (e.g., "app/Services/**", "src/components/**").
- **tags** (array of strings) - Optional - Filters results by semantic tags (e.g., ["stripe", "payment"]).
- **lang** (array of strings) - Optional - Filters results by programming language (e.g., ["php", "typescript"]).
- **provider** (string) - Optional - Overrides the embedding provider (e.g., "auto", "openai", "transformers").
- **hybrid** (string) - Optional - Enables hybrid search (combining semantic and keyword search) ("on" or "off").
- **bm25** (string) - Optional - Enables BM25 keyword search ("on" or "off").
- **reranker** (string) - Optional - Uses a cross-encoder reranker for improved relevance ("off" or "transformers").
- **symbol_boost** (string) - Optional - Enables symbol-aware ranking for better accuracy ("on" or "off").

### Request Example
```json
{
  "query": "user authentication logic",
  "limit": 5,
  "path_glob": "src/auth/**",
  "tags": ["security"]
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of search results. Each result contains:
  - **file** (string) - The path to the file.
  - **symbol** (string) - The symbol (e.g., function, class) found.
  - **line** (integer) - The line number where the symbol is located.
  - **similarity** (float) - The similarity score of the result.
  - **sha** (string) - The git SHA of the code chunk.
  - **meta** (object) - Additional metadata about the result.
```

--------------------------------

### Code Retrieval and Analysis API

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

APIs for retrieving specific code chunks, project statistics, and activating context packs for focused searches.

```APIDOC
## GET /get_code_chunk

### Description
Retrieves the complete source code of a specific code chunk identified by its SHA.

### Method
GET

### Endpoint
/get_code_chunk

### Parameters
#### Query Parameters
- **sha** (string) - Required - SHA identifier from search results.
- **path** (string) - Optional - Project root directory. Defaults to ".".

### Request Example
```json
{
  "sha": "abcdef1234567890",
  "path": "."
}
```

### Response
#### Success Response (200)
- **code** (string) - The complete source code of the requested chunk.

#### Response Example
```json
{
  "code": "// Source code content..."
}
```

## GET /get_project_stats

### Description
Provides an overview and statistics for the project, including file counts, detected languages, and function statistics.

### Method
GET

### Endpoint
/get_project_stats

### Parameters
#### Query Parameters
- **path** (string) - Optional - Directory to analyze. Defaults to ".".

### Request Example
```json
{
  "path": "."
}
```

### Response
#### Success Response (200)
- **total_functions** (integer) - Total number of functions indexed.
- **languages** (array of strings) - List of programming languages detected in the project.
- **files_by_language** (object) - An object detailing the count of files for each detected language.

#### Response Example
```json
{
  "total_functions": 150,
  "languages": ["javascript", "python"],
  "files_by_language": {
    "javascript": 45,
    "python": 12
  }
}
```

## POST /use_context_pack

### Description
Activates predefined search scopes and filters by applying a context pack. This sets default filters for subsequent `search_code` calls.

### Method
POST

### Endpoint
/use_context_pack

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the context pack to activate (e.g., 'stripe-backend', 'react-components').
- **path** (string) - Optional - Project root directory. Defaults to ".".

### Request Example
```json
{
  "name": "stripe-backend",
  "path": "."
}
```

### Response
#### Success Response (200)
Indicates that the context pack has been successfully activated.

#### Response Example
```json
{
  "message": "Context pack 'stripe-backend' activated."
}
```
```

--------------------------------

### PAMPA Tool: update_project

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Documentation for the `update_project` tool, used to synchronize the PAMPA index with recent changes made to the project's codebase.

```APIDOC
## POST /tools/update_project

### Description
Updates the existing index for a project to reflect any recent changes in the codebase. This ensures that PAMPA's memory remains synchronized with the latest code modifications.

### Method
POST

### Endpoint
`/tools/update_project`

### Parameters
#### Request Body
- **path** (string) - Required - The file path to the project root directory whose index needs to be updated.
- **provider** (string) - Optional - Specifies the embedding provider to use for updating embeddings (e.g., "auto", "openai", "transformers"). Defaults to "auto" if not provided.

### Request Example
```json
{
  "path": "/path/to/your/project"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating that the project index has been updated.
```

--------------------------------

### Enable Incremental Updates with Watching

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Starts Pampa in watch mode to enable incremental updates. This feature helps speed up indexing by only processing changed files.

```bash
pampa watch
```

--------------------------------

### Search Code with PAMPA

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Illustrates searching for code within a project using PAMPA, highlighting the traditional and new explicit methods for directory specification.

```bash
# Traditional way
pampa search "create policy" /path/to/project

# New clearer options
pampa search "create policy" --project /path/to/project
pampa search "create policy" --directory /path/to/project
```

--------------------------------

### PAMPA Tool: get_code_chunk

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Documentation for the `get_code_chunk` tool, used to retrieve the complete code content of a specific code chunk identified by its SHA and file path.

```APIDOC
## POST /tools/get_code_chunk

### Description
Retrieves the full source code content for a specific code chunk identified by its SHA (Secure Hash Algorithm) and file path.

### Method
POST

### Endpoint
`/tools/get_code_chunk`

### Parameters
#### Request Body
- **sha** (string) - Required - The git SHA of the code chunk to retrieve.
- **path** (string) - Required - The path to the file containing the code chunk.

### Request Example
```json
{
  "sha": "a1b2c3d4e5f678901234567890abcdef12345678",
  "path": "src/utils/helpers.js"
}
```

### Response
#### Success Response (200)
- **code** (string) - The complete source code content of the requested code chunk.
```

--------------------------------

### Start File Watcher with Default Settings

Source: https://context7.com/tecnomanu/pampa/llms.txt

Initiates the Pampa file watcher with default debounce settings (500ms) and a specified provider. This command monitors project files for changes and updates the index incrementally.

```bash
npx pampa watch /path/to/project --provider transformers
```

--------------------------------

### Pampa CLI: Table of Commands

Source: https://github.com/tecnomanu/pampa/blob/master/README.md

A reference table outlining various Pampa CLI commands and their purposes, including indexing, searching, and managing context packs.

```markdown
| Command                                  | Purpose                                                  |
| ---------------------------------------- | -------------------------------------------------------- |
| `npx pampa index [path] [--provider X]`  | Create or refresh the full index at the provided path    |
| `npx pampa update [path] [--provider X]` | Force a full re-scan (helpful after large refactors)     |
| `npx pampa watch [path] [--provider X]`  | Incrementally update the index as files change           |
| `npx pampa search <query>`               | Hybrid BM25 + vector search with optional scoped filters |
| `npx pampa context <list | show | use>` | Manage reusable context packs for search defaults |
| `npx pampa mcp`                          | Start the MCP stdio server for editor/agent integrations |
```

--------------------------------

### PAMPA Clarity Improvement

Source: https://github.com/tecnomanu/pampa/blob/master/DEMO_MULTI_PROJECT_EN.md

Compares the less clear traditional method of specifying project paths with the new, more explicit `--project` option in PAMPA.

```bash
# ❌ Before: Not so clear
pampa search "function" /some/long/path/to/project

# ✅ Now: Much clearer
pampa search "function" --project /some/long/path/to/project
```

--------------------------------

### Retrieve Code Chunk by SHA

Source: https://github.com/tecnomanu/pampa/blob/master/README_FOR_AGENTS.md

Fetches the complete source code for a specific code chunk identified by its SHA. Requires the SHA identifier from search results and optionally the project root path.

```python
get_code_chunk(sha, path=".")
```

--------------------------------

### MCP Configuration Update (JSON)

Source: https://github.com/tecnomanu/pampa/blob/master/MIGRATION_GUIDE_v1.12.md

Shows the updated MCP (Multi-Command Protocol) configuration for PAMPA v1.12. This JSON snippet details how to specify the command and arguments for running the latest PAMPA version within an MCP setup.

```json
{
	"mcpServers": {
		"pampa": {
			"command": "npx",
			"args": ["-y", "pampa@latest", "mcp"]
		}
	}
}
```

--------------------------------

### Get Project Overview and Statistics (JavaScript)

Source: https://context7.com/tecnomanu/pampa/llms.txt

The `get_project_stats` tool provides an overview of the indexed project, including a summary of its structure and top functions/classes organized by file and language. It's useful for checking if a project is indexed and understanding its composition.

```javascript
// MCP Tool: get_project_stats
get_project_stats({
  path: "/path/to/project"
})

// Returns project overview:
{
  "success": true,
  "results": [
    { "path": "app/Http/Controllers/AuthController.php", "meta": { "symbol": "login" }, "lang": "php" },
    { "path": "app/Http/Controllers/AuthController.php", "meta": { "symbol": "register" }, "lang": "php" },
    { "path": "app/Services/Payment/StripeService.php", "meta": { "symbol": "createCheckoutSession" }, "lang": "php" },
    { "path": "src/components/LoginForm.tsx", "meta": { "symbol": "LoginForm" }, "lang": "tsx" }
  ]
}

// CLI equivalent for detailed info
// $ npx pampa info
// Output:
// PAMPA project information
// Total indexed functions: 247
//
// By language:
//   php: 180 functions
//   typescript: 45 functions
//   javascript: 22 functions
//
// Files with most functions:
//   app/Services/StripeService.php: 15 functions
//   app/Http/Controllers/UserController.php: 12 functions
```

--------------------------------

### Run Default Benchmark

Source: https://context7.com/tecnomanu/pampa/llms.txt

Executes the default benchmark suite to evaluate search quality metrics such as Precision@1, MRR@5, and nDCG@10 across different search modes (Base, Hybrid, Hybrid+CE).

```bash
npm run bench
```