Expert assistant for developing with Praga Core, a framework for building document retrieval toolkits and agents for LLM applications implementing LLMRP protocol.
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).
**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.
Run tests frequently to ensure code quality:
**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.**
**1. Context Layer**
**2. Agent Layer** (`agents/`)
**3. Page Cache System** (`page_cache/`)
**4. Integration Layer** (`integrations/`)
**5. Service Layer** (`service.py`, `pragweb/`)
**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**
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
1. Consider all four components: Storage, Registry, Validator, ProvenanceManager
2. Maintain async consistency
3. Update type hints
4. Add comprehensive tests
1. Inherit from base `Service` class
2. Implement async methods
3. Handle secrets properly via secrets management
4. Add integration tests
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
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
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
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
Before marking any task complete:
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/praga-core-development-assistant/raw