Praga Core Development Assistant

You are an expert assistant for working with the Praga Core codebase, a framework for building document retrieval toolkits and agents for LLM applications using the LLMRP (LLM Retrieval Protocol).

Environment Setup

**CRITICAL FIRST STEP:** At the start of every session, activate the virtual environment:

```bash

source .venv/bin/activate

```

All subsequent commands require the venv to be active.

Core Development Workflow

Testing Strategy

Run tests frequently to ensure code quality:

Code Quality Commands

**ALWAYS run these after making changes:**

1. `black .` - Format code with Black (88-character line length)

2. `isort .` - Sort imports (Black profile)

3. `flake8 .` - Lint code with extended rules

4. `mypy src/` - Type check source code (strict mode)

5. `autoflake8 --in-place --recursive .` - Remove unused imports

**Fix all linting and test issues before completing tasks.**

Build Commands

Architecture Understanding

Core Components

**1. Context Layer**

**2. Agent Layer** (`agents/`)

**3. Page Cache System** (`page_cache/`)

**4. Integration Layer** (`integrations/`)

**5. Service Layer** (`service.py`, `pragweb/`)

Critical Design Patterns

**Async-First Architecture**

**Action System Signature Transformation**

This is a sophisticated pattern central to Praga Core:

1. **Define actions with `Page` parameters:**

```python

@context.action()

def mark_email_read(email: EmailPage) -> bool:

email.read = True

return True

```

2. **The `@action` decorator automatically creates wrappers that:**

- Accept `PageURI` parameters externally

- Use `context.get_pages()` for bulk async page retrieval

- Call the original function with resolved `Page` objects

3. **Invoke actions with `PageURI` only:**

```python

result = await context.invoke_action("mark_email_read", {"email": page_uri})

```

4. **API boundary strictly enforces PageURI-only interface**

- External API rejects `Page` objects with helpful errors

- Internal logic works with `Page` objects

- Clean separation between external and internal interfaces

**Mixin-Based Composition**

**Type Safety**

**Separation of Concerns**

**Protocol-Based Design**

Development Guidelines

When Adding Actions

1. Define action with `Page` parameters (internal logic)

2. The `@action` decorator handles PageURI transformation automatically

3. Never manually accept `Page` objects in public APIs

4. Always use `context.invoke_action()` with `PageURI` arguments

5. Test both internal logic and external API interface

When Modifying Page Cache

1. Consider all four components: Storage, Registry, Validator, ProvenanceManager

2. Maintain async consistency

3. Update type hints

4. Add comprehensive tests

When Working with Services

1. Inherit from base `Service` class

2. Implement async methods

3. Handle secrets properly via secrets management

4. Add integration tests

Code Quality Standards

Testing Requirements

Common Tasks

Adding a New Action

1. Define function with `Page` parameters in appropriate context

2. Apply `@context.action()` decorator

3. Implement logic using Page object attributes

4. Write tests for both Page-based logic and PageURI-based invocation

5. Run code quality checks

6. Update documentation if needed

Adding a New Service

1. Create service class inheriting from `Service`

2. Implement async methods for API operations

3. Add secrets management if needed

4. Create corresponding Page types if applicable

5. Write comprehensive tests

6. Run code quality checks

Modifying Page Cache

1. Identify which component needs changes (Storage/Registry/Validator/Provenance)

2. Update relevant component maintaining async patterns

3. Update type hints

4. Add/update tests for affected functionality

5. Verify no performance regressions

6. Run full test suite

Debugging

1. Check if venv is activated

2. Verify async/await usage is correct

3. Ensure PageURI vs Page distinction is maintained

4. Check type hints with mypy

5. Review test output carefully

6. Use pytest verbose mode for detailed output

Final Checklist

Before marking any task complete: