### Run Potpie

Source: https://github.com/potpie-ai/potpie/blob/main/GETTING_STARTED.md

Commands to make the start script executable and then run the Potpie application.

```bash
chmod +x start.sh
./start.sh
```

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

### Set Up Development Environment

Source: https://github.com/potpie-ai/potpie/blob/main/GETTING_STARTED.md

Commands to create a virtual environment, activate it, and install project dependencies using pip.

```bash
python3.10 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

```bash
pip install -r requirements.txt --use-deprecated=legacy-resolver
```

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

### Potpie Slack Integration Setup

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Instructions for setting up the Potpie Slack integration. This involves installing the app from the provided link and following the configuration steps outlined in the Potpie documentation.

```APIDOC
Slack Integration:
  Setup:
    - Install the Potpie Slack App from: https://slack.potpie.ai/slack/install
    - Refer to Potpie docs for configuration: https://docs.potpie.ai/extensions/slack
  Features:
    - Access Potpie agents within Slack.
    - Contextual assistance in Slack threads.
    - Team collaboration.
```

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

### Run Potpie Application

Source: https://github.com/potpie-ai/potpie/blob/main/GETTING_STARTED.md

Executes the main startup script for the Potpie AI application.

```bash
./start.sh
```

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

### Make start.sh executable

Source: https://github.com/potpie-ai/potpie/blob/main/GETTING_STARTED.md

Grants execute permissions to the start.sh script, allowing it to be run directly.

```bash
chmod +x start.sh
```

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

### Starting Potpie Services

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Shell commands to start all Potpie services, including Docker services, database migrations, and the FastAPI application. Requires execute permissions on the start script.

```bash
chmod +x start.sh
./start.sh
```

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

### Starting Potpie Services (Windows)

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

PowerShell command to start all Potpie services on a Windows environment.

```powershell
./start.ps1
```

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

### Initialize gcloud CLI

Source: https://github.com/potpie-ai/potpie/blob/main/GETTING_STARTED.md

Initializes the Google Cloud SDK command-line interface, setting up default configurations for your environment. This includes selecting a default region and project.

```bash
gcloud init
```

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

### LLM Reflection: Caching System Approaches

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Example prompt requesting multiple caching system implementations and their comparative analysis.

```python
"Generate three different approaches to implement a caching system for our API responses:

1. An in-memory LRU cache using a custom data structure
2. A Redis-based distributed cache solution
3. A file-system based approach with TTL

For each approach, analyze time complexity, memory usage, scalability across multiple servers, and implementation complexity."
```

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

### Virtual Environment and Dependency Installation

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Commands to create a Python virtual environment and install project dependencies using pip. This ensures a clean and isolated environment for the project.

```bash
python3.10 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

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

### Format PEM Key

Source: https://github.com/potpie-ai/potpie/blob/main/GETTING_STARTED.md

Script to format a PEM private key for use with GitHub integration.

```bash
chmod +x format_pem.sh
./format_pem.sh your-key.pem
```

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

### Potpie VSCode Extension Installation

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Information on how to install the Potpie VSCode extension for direct integration within the development environment. It allows access to Potpie agents without leaving the editor.

```APIDOC
VSCode Extension:
  Installation:
    - Install directly from the VSCode Marketplace: https://marketplace.visualstudio.com/items?itemName=PotpieAI.potpie-vscode-extension
  Features:
    - Direct integration of Potpie agents within VSCode.
    - Quick setup process.
    - Seamless workflow for coding assistance.
```

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

### Initialize Potpie UI Submodule

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Instructions for initializing the Potpie UI submodule, which involves updating and checking out the main branch, setting up the environment variables, building the frontend, and starting the application.

```bash
git submodule update --init
cd potpie-ui
git checkout main
git pull origin main
cp .env.template .env
pnpm build
pnpm start
```

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

### Detailed Context Example: Authentication System

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Demonstrates how to provide specific context for code generation, contrasting a poor prompt with a better, more detailed one that includes technology stack, security requirements, and references to existing codebase elements.

```text
❌ Poor: "Create a user authentication system."

✅ Better: "Create a JWT-based authentication system for a Node.js Express API that integrates with our MongoDB user collection. The system should handle password hashing with bcrypt, issue tokens valid for 24 hours, and implement refresh token rotation for security. Our existing middleware pattern uses async/await syntax. Refer to @authMiddleware.js for the middleware structure and @userModel.js for the user schema."
```

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

### Persona-Based Code Generation: Security Focus

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Example prompt for generating a secure user registration system by adopting a senior security engineer persona.

```python
"Act as a senior security engineer conducting a code review. Create a user registration system in Python/Django that implements proper password handling, input validation, and protection against common web vulnerabilities."
```

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

### Commit Changes

Source: https://github.com/potpie-ai/potpie/blob/main/contributing.md

Example of how to commit code changes with a descriptive message in the imperative mood.

```bash
git commit -m "Add feature to handle XYZ"
```

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

### Regenerate Code for Sorting Algorithm

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Example prompt for regenerating code to improve sorting algorithm complexity from O(n²) to O(n log n) using merge sort.

```python
"Let's try a different approach for the sorting algorithm. The previous implementation had O(n²) complexity, which won't work for our dataset size. Please regenerate the solution focusing on an O(n log n) approach using a merge sort pattern similar to what we use in our other data processing functions."
```

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

### API: List Available Agents

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Retrieves a list of available agents, with an option to include system agents. Useful for identifying agent IDs for conversation setup.

```APIDOC
GET /api/v1/list-available-agents/

Query Parameters:
  list_system_agents: Boolean (true/false) to include system agents.

Response:
{
  "agents": [
    {
      "agent_id": "chosen-agent-id",
      "name": "Agent Name"
    }
  ]
}
```

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

### Implement Chain of Thought Prompting for Complex Logic

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Chain of thought prompting guides LLMs through sequential reasoning stages (conceptual explanation, pseudocode, implementation details, final code) to improve accuracy and visibility for complex algorithms and data transformations.

```APIDOC
Sequential reasoning stages to request:

- Initial explanation of the conceptual approach
- Pseudocode outline of the solution
- Implementation details for each component
- Complete integrated implementation
```

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

### Potpie API Access and Agent Interaction

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

This documentation outlines the key API operations for interacting with Potpie Agents. It covers generating API keys, parsing repositories to get project IDs, monitoring parsing status, creating conversations with agents, and sending messages within those conversations. These functionalities enable programmatic control and integration of Potpie's capabilities.

```APIDOC
Potpie API Documentation:

1. Generate an API Key:
   - Purpose: Create a secure API key for accessing Potpie services.
   - Usage: Typically done through the Potpie user interface or a dedicated API endpoint.

2. Parse Repositories:
   - Endpoint: /api/v1/parse/repositories
   - Method: POST
   - Description: Analyzes a code repository to extract information and generate a project ID.
   - Input: Repository URL or path.
   - Output: Project ID for subsequent interactions.

3. Monitor Parsing Status:
   - Endpoint: /api/v1/parse/status/{projectId}
   - Method: GET
   - Description: Checks the progress and completion status of a repository parsing request.
   - Input: Project ID obtained from the parsing operation.
   - Output: Status information (e.g., pending, processing, completed, failed).

4. Create Conversations:
   - Endpoint: /api/v1/conversations
   - Method: POST
   - Description: Initiates a new conversation with a specific agent for a given project.
   - Input:
     - projectId: The ID of the project to associate the conversation with.
     - agentId: The ID of the agent to converse with.
   - Output: Conversation ID for subsequent messaging.

5. Send Messages:
   - Endpoint: /api/v1/conversations/{conversationId}/messages
   - Method: POST
   - Description: Sends a message to an ongoing conversation with an agent.
   - Input:
     - conversationId: The ID of the conversation.
     - message: The content of the message to send.
   - Output: Agent's response to the message.
```

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

### Parse Directory API Endpoint

Source: https://github.com/potpie-ai/potpie/blob/main/docs/parsing.md

This section details the POST endpoint for parsing a directory. It includes the request body schema, expected response schema, example requests and responses, and possible status codes.

```APIDOC
Base URL: /parse/

Endpoint: /parse
Method: POST

Request Body:
  Type: ParsingRequest
  Description: Contains the details required to parse a directory.
  Schema:
    {
      "repo_name": "string",      // Name of the repository (optional if repo_path is provided)
      "repo_path": "string",      // Local path to the repository (optional if repo_name is provided)
      "branch_name": "string"     // Name of the branch to parse
    }

Response:
  Type: ParsingResponse
  Description: Returns the result of the parsing operation.
  Schema:
    {
      "message": "string",        // Confirmation message
      "status": "string",         // Status of the parsing operation
      "project_id": "string"      // Unique identifier for the parsed project
    }

Example Request:
    {
      "repo_name": "user/repo",
      "branch_name": "main"
    }

Example Response:
    {
      "message": "The project has been parsed successfully.",
      "status": "READY",
      "project_id": "12345"
    }

Possible Status Codes:
  200 OK: Parsing completed successfully.
  400 Bad Request: Invalid input data.
  403 Forbidden: Access denied due to restrictions.
  500 Internal Server Error: Unexpected server error.
```

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

### Initialize Linear Issue Tools

Source: https://github.com/potpie-ai/potpie/blob/main/app/modules/intelligence/tools/linear_tools/README.md

Demonstrates initializing Linear issue fetching and updating tools within a ToolService, requiring a database session and user ID.

```python
# In ToolService._initialize_tools
tools = {
    # Other tools...
    "get_linear_issue": get_linear_issue_tool(self.db, self.user_id),
    "update_linear_issue": update_linear_issue_tool(self.db, self.user_id),
}
```

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

### Model Selection Considerations for Code Generation Tasks

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Provides a comparative overview of how different LLM strengths align with specific code generation tasks, highlighting factors like context window capacity, language proficiency, and domain knowledge.

```text
| Task                          | Model Selection Consideration |
|-------------------------------|--------------------------------|
| Complex enterprise architecture | Models with larger context windows excel at maintaining consistency across large codebases |
| ML pipeline implementation    | Models with stronger mathematics and data science training perform better |
| Frontend component generation | Models with recent training on modern frameworks provide up-to-date patterns |
```

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

### Clarify Technical Constraints for Code Generation

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Specifying language, framework, and library versions ensures compatibility. This includes details like Python version, FastAPI and Pydantic versions, ORM choices (SQLAlchemy vs. raw SQL), and authentication methods (JWT).

```APIDOC
Generate a REST API endpoint using:

- Python 3.9
- FastAPI 0.95 with Pydantic v2 models
- SQLAlchemy 2.0 for database queries
- JWT authentication using our existing AuthManager from auth_utils.py
- Must be compatible with our PostgreSQL 13 database
```

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

### Clone Potpie Repository

Source: https://github.com/potpie-ai/potpie/blob/main/contributing.md

Steps to fork and clone the Potpie repository, and set up the upstream remote for tracking changes from the main repository.

```bash
git clone https://github.com/your-username/potpie.git
cd potpie
git remote add upstream https://github.com/potpie-ai/potpie.git
```

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

### Specificity in Existing Patterns: User Data Processing

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Illustrates the importance of referencing specific implementation patterns and code locations when requesting code modifications, contrasting a vague request with a precise one that specifies the class, method, and coding style.

```text
❌ Poor: "Write a function to process user data."

✅ Better: "Create a new method in the UserProcessor class (src/services/UserProcessor.js) that transforms user data following the same functional approach used in the transformPaymentData method. Prioritize readability over performance as this runs asynchronously."
```

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

### Environment Configuration (.env.template)

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Defines essential environment variables for Potpie AI, including database connections, API keys, model configurations, and development settings. Ensure these are correctly set in your `.env` file.

```bash
isDevelopmentMode=enabled
ENV=development
POSTGRES_SERVER=postgresql://postgres:mysecretpassword@localhost:5432/momentum
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=mysecretpassword
REDISHOST=127.0.0.1
REDISPORT=6379
BROKER_URL=redis://127.0.0.1:6379/0
CELERY_QUEUE_NAME=dev
defaultUsername=defaultuser
PROJECT_PATH=projects
{PROVIDER}_API_KEY=sk-proj-your-key
INFERENCE_MODEL=ollama_chat/qwen2.5-coder:7b
CHAT_MODEL=ollama_chat/qwen2.5-coder:7b
```

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

### Version Control and Git Integration

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

Libraries for interacting with Git repositories and GitHub.

```python
gitPython==3.1.43
PyGithub==2.5.0
```

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

### Push to Fork

Source: https://github.com/potpie-ai/potpie/blob/main/contributing.md

Command to push local commits to your forked repository on GitHub.

```bash
git push origin feature/your-feature-name
```

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

### Development and Linting Tools

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

Includes tools for development workflow, code formatting, linting, and security analysis, such as pre-commit, isort, black, ruff, pylint, and bandit.

```python
pre-commit==4.0.1
isort==5.13.2
black==24.10.0
ruff==0.8.1
pylint==3.3.2
bandit==1.8.0
```

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

### Test Linear Client

Source: https://github.com/potpie-ai/potpie/blob/main/app/modules/intelligence/tools/linear_tools/README.md

Executes a test for the Linear client, requiring a user ID to verify API key configuration.

```bash
python -m app.modules.intelligence.tools.linear_tools.test_client --user-id=user-uuid-here
```

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

### API: Initialize Repository Parsing

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Endpoint to initiate the parsing of a code repository. Supports both local paths (development) and remote repository names (production). Returns a project ID upon successful initiation.

```APIDOC
POST /api/v1/parse
Content-Type: application/json

Request Body (Development):
{
  "repo_path": "path/to/local/repo",
  "branch_name": "main"
}

Request Body (Production):
{
  "repo_name": "owner/repo-name",
  "branch_name": "main"
}

Response:
{
  "project_id": "your-project-id"
}
```

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

### Linear Integration API

Source: https://github.com/potpie-ai/potpie/blob/main/app/modules/intelligence/tools/linear_tools/README.md

Provides an overview of the Linear integration's API, detailing the primary functions for interacting with Linear issues and the configuration methods for API keys.

```APIDOC
Linear Integration Tools:

Overview:
  Tools to interact with Linear issues.
  - get_linear_issue: Fetch details of a Linear issue by ID.
  - update_linear_issue: Update a Linear issue with new details.

API Key Configuration:
  1. Environment Variable (Global):
     Set LINEAR_API_KEY in your environment.
     Example:
       export LINEAR_API_KEY=your_linear_api_key

  2. User-Specific API Keys (Recommended):
     Configure via secret management system.
     Endpoint: POST /configure-linear
     Request Body:
       CreateIntegrationKeyRequest:
         integration_keys: List[IntegrationKey]
           IntegrationKey:
             service: str (e.g., "linear")
             api_key: str
     Response:
       {"message": "Linear API key configured successfully"}

Tool Usage:
  Tools require user context (db session and user_id) during initialization.
  Example Initialization:
    get_linear_issue_tool(db_session, user_id)
    update_linear_issue_tool(db_session, user_id)

  Example Direct Usage:
    tool = get_linear_issue_tool(db, user_id)
    await tool.func(issue_id="ISSUE-123")

Testing:
  Run tests with user ID:
    python -m app.modules.intelligence.tools.linear_tools.test_client --user-id=user-uuid-here

Implementation Details:
  - Tools are self-contained classes.
  - Client prioritizes user-specific keys, falls back to environment variables.
  - Raises error if no API key is available.
  - `db` and `user_id` are required for tool initialization.
```

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

### Potpie Tooling System Commands

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

This section details the commands available in Potpie's tooling system, which agents use to interact with the knowledge graph and infrastructure. These commands cover retrieving code, querying the knowledge graph, detecting changes, and accessing file structures.

```APIDOC
Tooling System Commands:

get_code_from_probable_node_name
  - Retrieves code snippets based on a probable node name.

get_code_from_node_id
  - Fetches code associated with a specific node ID.

get_code_from_multiple_node_ids
  - Retrieves code snippets for multiple node IDs simultaneously.

ask_knowledge_graph_queries
  - Executes vector similarity searches to obtain relevant information.

get_nodes_from_tags
  - Retrieves nodes tagged with specific keywords.

get_code_graph_from_node_id/name
  - Fetches code graph structures for a specific node.

change_detection
  - Detects changes in the current branch compared to the default branch.

get_code_file_structure
  - Retrieves the file structure of the codebase.
```

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

### Utility and Asynchronous Libraries

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

Lists utility libraries for various tasks, including asynchronous file operations, HTTP requests, and system utilities.

```python
python-dotenv==1.0.1
tree-sitter==0.20.4
tree-sitter-languages==1.10.2
tqdm==4.67.1
grep-ast==0.4.1
pygments==2.18.0
networkx==3.4.2
blar-graph==1.1.6
uuid6==2024.7.10
aiohttp==3.11.9
aiofiles==24.1.0
requests==2.32.3
```

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

### AI and Machine Learning Libraries

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

Lists essential libraries for AI and machine learning tasks, including transformers for NLP models, torch for deep learning, scikit-learn for general ML, and OpenAI for API integration.

```python
openai==1.74.0
transformers>=4.48.0
torch==2.5.1
scikit-learn==1.5.2
```

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

### Database and ORM Dependencies

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

This section details the database-related packages, including SQLAlchemy for ORM and specific database drivers like psycopg2-binary for PostgreSQL and neo4j for graph databases.

```python
sqlalchemy==2.0.36
alembic==1.14.0
postgres==4.0
psycopg2-binary==2.9.10
neo4j==5.27.0
langchain-postgres==0.0.12
```

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

### Direct Usage of get_linear_issue_tool

Source: https://github.com/potpie-ai/potpie/blob/main/app/modules/intelligence/tools/linear_tools/README.md

Shows how to directly use the `get_linear_issue_tool` by providing a database session and user ID, then calling the tool's function with an issue ID.

```python
from app.modules.intelligence.tools.linear_tools import get_linear_issue_tool
from sqlalchemy.orm import Session
from app.core.database import get_db

# Get database session
db = next(get_db())

# Create a tool with user context (both parameters are required)
tool = get_linear_issue_tool(db, user_id)

# Use the tool (user context is already applied)
issue_data = await tool.func(issue_id="ISSUE-123")
```

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

### Additional API Notes

Source: https://github.com/potpie-ai/potpie/blob/main/docs/parsing.md

Provides additional notes for API usage, including environment variable requirements for local parsing and user ID constraints for remote repositories.

```APIDOC
Additional Notes:
- Ensure that the environment variable `isDevelopmentMode` is set to "enabled" to parse local repositories.
- The `user_id` must not match the `defaultUsername` environment variable when parsing remote repositories.
```

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

### API: Create Conversation

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Initiates a new conversation with specified user, project, and agent IDs. Returns a conversation ID for subsequent messaging.

```APIDOC
POST /api/v1/conversations/
Content-Type: application/json

Request Body:
{
  "user_id": "your_user_id",
  "title": "My First Conversation",
  "status": "active",
  "project_ids": ["your-project-id"],
  "agent_ids": ["chosen-agent-id"]
}

Response:
{
  "conversation_id": "your-conversation-id"
}
```

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

### Configure Linear API Key

Source: https://github.com/potpie-ai/potpie/blob/main/app/modules/intelligence/tools/linear_tools/README.md

Configures a user-specific Linear API key using the secret management system. It takes the API key as input and stores it associated with the authenticated user.

```python
from app.modules.key_management.secret_manager import SecretManager
from fastapi import Depends
from sqlalchemy.orm import Session

from app.core.database import get_db
from app.modules.auth.auth_service import AuthService

@router.post("/configure-linear")
async def configure_linear_api_key(
    api_key: str,
    user=Depends(AuthService.check_auth),
    db: Session = Depends(get_db),
):
    # Create an integration key request
    from app.modules.key_management.secrets_schema import (
        CreateIntegrationKeyRequest,
        IntegrationKey,
    )

    request = CreateIntegrationKeyRequest(
        integration_keys=[
            IntegrationKey(
                service="linear",
                api_key=api_key
            )
        ]
    )

    # Store the key in the secret manager
    SecretManager.create_integration_keys(
        request=request,
        user=user,
        db=db
    )

    return {"message": "Linear API key configured successfully"}
```

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

### Create Development Branch

Source: https://github.com/potpie-ai/potpie/blob/main/contributing.md

How to create a new Git branch for feature development or bug fixes, following a naming convention.

```bash
git checkout -b feature/your-feature-name
```

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

### Core Project Dependencies

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

This snippet lists the primary Python packages and their versions required for the Potpie AI project. It includes web frameworks, AI/ML libraries, data connectors, and utility tools.

```python
fastapi[all]==0.115.6
instructor==1.5.2
jiter==0.5.0
litellm==1.72.1
joblib==1.4.2
json_repair==0.35.0
langsmith==0.3.3
json5==0.9.28
kombu==5.4.2
uvicorn==0.32.1
sentence-transformers==4.0.2
crewai==0.95.0
nltk==3.9.1
celery==5.4.0
redis==5.2.0
flower==2.0.1
chardet==5.2.0
sentry-sdk[fastapi]==2.20.0
posthog==3.7.4
newrelic==9.0.0
tiktoken==0.7.0
agentops==0.3.26
pydantic[email]==2.10.3
firecrawl-py==1.11.1
pydantic_ai==0.1.3
pathspec==0.12.1
pytest
pytest-asyncio
```

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

### Cloud and External Service Integrations

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

Dependencies for interacting with external services and cloud platforms, such as Firebase, Google Cloud Secret Manager, and Resend for email.

```python
firebase-admin==6.6.0
portkey-ai==1.10.3
google-cloud-secret-manager==2.21.1
resend==2.4.0
```

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

### Set Global Linear API Key

Source: https://github.com/potpie-ai/potpie/blob/main/app/modules/intelligence/tools/linear_tools/README.md

Sets the Linear API key using a bash environment variable for global fallback.

```bash
export LINEAR_API_KEY=your_linear_api_key
```

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

### Specify Edge Cases and Constraints for Robust Code

Source: https://github.com/potpie-ai/potpie/wiki/How-to-write-good-prompts-for-generating-code-from-LLMs

Define technical edge cases such as boundary values, resource limitations, and exceptional conditions to improve code robustness. This includes handling empty inputs, large files, malformed data, concurrency, and network interruptions.

```APIDOC
Implement a file processing function that handles:

- Empty files (return empty result)
- Files exceeding 1GB (process in chunks)
- Malformed CSV data (log error, continue processing valid rows)
- Concurrent access (implement appropriate locking)
- Network interruptions (implement resume capability)
```

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

### Environment Variables: ENV vs. isDevelopmentMode

Source: https://github.com/potpie-ai/potpie/blob/main/contributing.md

Explanation of the difference between `ENV` and `isDevelopmentMode` environment variables in the Potpie application. `ENV` controls the deployment environment (dev, stage, prod), while `isDevelopmentMode` enables running without certain dependencies for local development.

```APIDOC
Environment Variables:

ENV: Specifies the application's running environment (e.g., 'development', 'staging', 'production'). This dictates which configuration settings are loaded.

isDevelopmentMode: A flag that enables running the application without certain dependencies (like Firebase, GitHub configuration, etc.). This is useful for local parsing and development scenarios where these external services are not required.

Key Differences:
- `ENV=development` still requires dependencies like Firebase/GCP/GitHub for local backend operation.
- `isDevelopmentMode=enabled` disables these dependencies to support running without them, facilitating local parsing and development.
```

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

### Create Custom Agent via API

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

This snippet demonstrates how to create a custom agent using the Potpie API. It sends a POST request to the specified endpoint with a JSON payload containing the agent's prompt. This is useful for automating the creation of specialized agents for tasks like root cause analysis from stack traces.

```bash
curl -X POST "http://localhost:8001/api/v1/custom-agents/agents/auto" \
     -H "Content-Type: application/json" \
     -d '{
             "prompt": "Aan agent that takes stacktrace as input and gives root cause analysis and proposed solution as output"
           }'
```

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

### LangChain Ecosystem Dependencies

Source: https://github.com/potpie-ai/potpie/blob/main/requirements.txt

Dependencies specifically for the LangChain framework, including core components, community integrations, and LangGraph for building agentic workflows.

```python
langchain==0.3.16
langchain-community==0.3.16
langchain-core==0.3.32
langgraph-checkpoint==2.0.10
langgraph-sdk==0.1.51
langgraph==0.2.58
```

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

### API: User Authentication

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Endpoint for user authentication. Sends email and password to obtain a bearer token for subsequent authenticated requests. This step can be skipped in development mode.

```APIDOC
POST /api/v1/login
Content-Type: application/json

Request Body:
{
  "email": "your-email",
  "password": "your-password"
}

Response:
{
  "token": "your_bearer_token"
}
```

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

### Conversations API Endpoints

Source: https://github.com/potpie-ai/potpie/blob/main/docs/conversations.md

Documentation for the Potpie AI Conversations API, detailing endpoints for managing conversations. Includes methods for creating, retrieving, and posting messages, along with request/response schemas and status codes.

```APIDOC
Base URL: /conversations/

1. Create a Conversation
  Endpoint: /conversations/
  Method: POST
  Request Body:
    Type: CreateConversationRequest
    Description: Contains the details required to create a conversation.
    Schema:
      {
        "user_id": "string",           // Unique identifier for the user creating the conversation
        "title": "string",             // Title of the conversation
        "status": "ConversationStatus", // Status of the conversation (active, archived, deleted)
        "project_ids": ["string"]      // List of project IDs associated with the conversation
      }
  Response:
    Type: CreateConversationResponse
    Description: Returns the details of the created conversation.
    Schema:
      {
        "message": "string",          // Confirmation message
        "conversation_id": "string"   // Unique identifier for the created conversation
      }
  Example Request:
    {
      "user_id": "user123",
      "title": "New Conversation",
      "status": "active",
      "project_ids": ["project1", "project2"]
    }
  Example Response:
    {
      "message": "Conversation created successfully.",
      "conversation_id": "123"
    }
  Possible Status Codes:
    201 Created: Conversation created successfully.
    400 Bad Request: Invalid input data.
    500 Internal Server Error: Unexpected server error.

2. Get Conversation Info
  Endpoint: /conversations/{conversation_id}/info/
  Method: GET
  Path Parameters:
    conversation_id: string - Unique identifier for the conversation.
  Response:
    Type: ConversationInfoResponse
    Description: Returns information about the specified conversation.
    Schema:
      {
        "id": "string",               // Unique identifier for the conversation
        "title": "string",            // Title of the conversation
        "status": "ConversationStatus", // Current status of the conversation
        "project_ids": ["string"],    // List of project IDs associated with the conversation
        "created_at": "datetime",     // Timestamp when the conversation was created
        "updated_at": "datetime",     // Timestamp when the conversation was last updated
        "total_messages": "int"       // Total number of messages in the conversation
      }
  Example Response:
    {
      "id": "123",
      "title": "New Conversation",
      "status": "active",
      "project_ids": ["project1", "project2"],
      "created_at": "2024-08-24T12:00:00Z",
      "updated_at": "2024-08-24T12:05:00Z",
      "total_messages": 5
    }
  Possible Status Codes:
    200 OK: Successfully retrieved conversation info.
    404 Not Found: Conversation not found.
    500 Internal Server Error: Unexpected server error.

3. Get Conversation Messages
  Endpoint: /conversations/{conversation_id}/messages/
  Method: GET
  Path Parameters:
    conversation_id: string - Unique identifier for the conversation.
  Query Parameters:
    start: int - The starting index for the messages. Default is 0.
    limit: int - The maximum number of messages to return. Default is 10.
  Response:
    Type: List[MessageResponse]
    Description: Returns a list of messages for the specified conversation.
  Example Response:
    [
      {
        "id": "msg1",
        "content": "Hello!",
        "sender": "user1",
        "timestamp": "2024-08-24T12:01:00Z"
      },
      {
        "id": "msg2",
        "content": "Hi there!",
        "sender": "user2",
        "timestamp": "2024-08-24T12:02:00Z"
      }
    ]
  Possible Status Codes:
    200 OK: Successfully retrieved messages.
    404 Not Found: Conversation not found.
    500 Internal Server Error: Unexpected server error.

4. Post a Message
  Endpoint: /conversations/{conversation_id}/message/
  Method: POST
  Path Parameters:
    conversation_id: string - Unique identifier for the conversation.
  Request Body:
    Type: MessageRequest
    Description: Contains the message content to be sent.
  Response:
    Type: StreamingResponse
    Description: Streams the response of the posted message.
  Example Request:
    {
      "content": "This is a new message."
    }
  Possible Status Codes:
    200 OK: Message posted successfully.
    400 Bad Request: Invalid message content.
    404 Not Found: Conversation not found.
    500 Internal Server Error: Unexpected server error.
```

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

### Schema Definitions

Source: https://github.com/potpie-ai/potpie/blob/main/docs/conversations.md

Defines the structure of request and response bodies used in the conversation management API. Includes schemas for creating conversations and retrieving conversation details.

```APIDOC
CreateConversationRequest:
  Description: Request body for creating a new conversation.
  Fields:
    user_id (string): Unique identifier for the user creating the conversation.
    title (string): Title of the conversation.
    status (ConversationStatus): Status of the conversation (e.g., active, archived).
    project_ids (List[string]): List of project IDs associated with the conversation.

CreateConversationResponse:
  Description: Response body for a created conversation.
  Fields:
    message (string): Confirmation message indicating success.
    conversation_id (string): Unique identifier for the created conversation.

ConversationInfoResponse:
  Description: Response body containing information about a conversation.
  Fields:
    id (string): Unique identifier for the conversation.
    title (string): Title of the conversation.
    status (ConversationStatus): Current status of the conversation.
    project_ids (List[string]): List of project IDs associated with the conversation.
    created_at (datetime): Timestamp when the conversation was created.
    updated_at (datetime): Timestamp when the conversation was last updated.
    total_messages (int): Total number of messages in the conversation.
```

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

### Common API Error Responses

Source: https://github.com/potpie-ai/potpie/blob/main/docs/parsing.md

This section outlines common error responses encountered when interacting with the API, including details for Bad Request, Forbidden, and Internal Server Errors.

```APIDOC
Error Handling:

Common Error Responses:

400 Bad Request
  Description: Invalid input data.
  Example Response:
    {
      "detail": "Invalid input data."
    }

403 Forbidden
  Description: Access denied due to restrictions.
  Example Response:
    {
      "detail": "Cannot parse remote repository without auth token."
    }

500 Internal Server Error
  Description: Unexpected server error.
  Example Response:
    {
      "detail": "Unexpected server error."
    }
```

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

### Stopping Potpie Services

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Shell commands to gracefully stop all Potpie services, including the FastAPI application, Celery worker, and Docker Compose services.

```bash
./stop.sh
```

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

### API: Monitor Parsing Status

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Endpoint to check the status of an ongoing repository parsing job using its project ID. Used to track progress until parsing is complete.

```APIDOC
GET /api/v1/parsing-status/{project_id}

Parameters:
  project_id: The ID of the parsing job to monitor.
```

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

### Stopping Potpie Services (Windows)

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

PowerShell command to gracefully stop all Potpie services on a Windows environment.

```powershell
./stop.ps1
```

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

### Conversation Management API

Source: https://github.com/potpie-ai/potpie/blob/main/docs/conversations.md

Provides endpoints for managing conversations within the Potpie AI project. Includes operations for regenerating messages, deleting conversations, and stopping generation processes. Each endpoint specifies the HTTP method, path parameters, expected request/response formats, and possible status codes.

```APIDOC
Regenerate Last Message:
  Endpoint: /conversations/{conversation_id}/regenerate/
  Method: POST
  Path Parameters:
    conversation_id (string): Unique identifier for the conversation.
  Response:
    Type: MessageResponse
    Description: Returns the regenerated last message.
  Example Response:
    {
      "id": "msg1",
      "content": "This is the regenerated message.",
      "sender": "user1",
      "timestamp": "2024-08-24T12:03:00Z"
    }
  Possible Status Codes:
    200 OK: Last message regenerated successfully.
    404 Not Found: Conversation not found.
    500 Internal Server Error: Unexpected server error.

Delete a Conversation:
  Endpoint: /conversations/{conversation_id}/
  Method: DELETE
  Path Parameters:
    conversation_id (string): Unique identifier for the conversation.
  Response:
    Type: dict
    Description: Confirms the deletion of the conversation.
  Example Response:
    {
      "message": "Conversation deleted successfully."
    }
  Possible Status Codes:
    200 OK: Conversation deleted successfully.
    404 Not Found: Conversation not found.
    500 Internal Server Error: Unexpected server error.

Stop Generation:
  Endpoint: /conversations/{conversation_id}/stop/
  Method: POST
  Path Parameters:
    conversation_id (string): Unique identifier for the conversation.
  Response:
    Type: dict
    Description: Confirms that the generation process has been stopped.
  Example Response:
    {
      "message": "Generation stopped successfully."
    }
  Possible Status Codes:
    200 OK: Generation stopped successfully.
    404 Not Found: Conversation not found.
    500 Internal Server Error: Unexpected server error.
```

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

### API: View Conversation History

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Retrieves the message history for a specific conversation, with options for pagination.

```APIDOC
GET /api/v1/conversations/{conversation_id}/messages/

Parameters:
  conversation_id: The ID of the conversation.

Query Parameters:
  start: The starting index for messages.
  limit: The maximum number of messages to retrieve.
```

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

### API: Send Message in Conversation

Source: https://github.com/potpie-ai/potpie/blob/main/README.md

Sends a message within an existing conversation to an agent. Allows for user queries and requests, potentially with associated node IDs.

```APIDOC
POST /api/v1/conversations/{conversation_id}/message/
Content-Type: application/json

Parameters:
  conversation_id: The ID of the conversation.

Request Body:
{
  "content": "Your question or request here",
  "node_ids":[]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.