From 793b966e776333f66ed4a3e7b4a3843fa79376dd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 19:25:22 +0000 Subject: [PATCH 1/2] Initial plan From ec21d56d44d743e1f6ac308f6a7ea9221d630263 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Mar 2026 19:27:00 +0000 Subject: [PATCH 2/2] chore: add .github/copilot-instructions.md for Copilot coding agent Co-authored-by: chrisk314 <2366658+chrisk314@users.noreply.github.com> Agent-Logs-Url: https://github.com/plugboard-dev/plugboard/sessions/cdc6bf08-f7c8-4580-86d0-fcd8f6b72a48 --- .github/copilot-instructions.md | 158 ++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..2bb5af98 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,158 @@ +# AI Agent Instructions for Plugboard + +This document provides guidelines for AI coding agents working on the Plugboard project. Following these instructions ensures contributions are consistent with the project's architecture, conventions, and style. + +## Project Overview + +Plugboard is an event-driven framework in Python for simulating and orchestrating complex processes with interconnected stateful components. Typical users are data scientists and engineers. + +### Core Architecture + +**Component**: The fundamental building block for modeling logic (see `plugboard/component/`). +- Lifecycle: `__init__` → `init` → `step` (repeated) → `destroy`. +- I/O declaration: Use class-level `io: IOController` attribute. Use this to specify inputs, outputs and events associated with a component. +- Business logic: Implement in the `step` method. +- Asynchronous: All lifecycle methods (`init`, `step`, `destroy`) must be `async`. + +**Process**: Orchestrates execution of components (see `plugboard/process/`) +- Manages collections of components and their interconnections. +- `LocalProcess`: Runs all components in a single process. +- Supports distributed execution via other process types, e.g. `RayProcess`. + +**Connector**: Defines communication channels between components (see `plugboard/connector/`). +- Links outputs to inputs: `component_name.output_name` → `component_name.input_name`. +- Various connector types available for different execution contexts. + +**State Management**: Tracks component and process status (see `plugboard/state/`). +- Critical for monitoring and distributed execution. +- Uses `StateBackend` abstraction. + +**Configuration**: Flexible process definition. +- Python-based: Direct component instantiation. +- YAML-based: Declarative configuration for CLI execution (`plugboard process run ...`). +- Relies on the Pydantic objects defined in `plugboard-schemas`. + +## Development Environment + +### Setup +- **Package Manager**: Uses `uv` for dependency management. +- **Dependencies**: Defined in `pyproject.toml`. +- **Python Version**: Requires Python 3.12 or higher. + +### Testing +- You can delegate to the `test` agent in `.github/agents` to update/add tests. +- **Framework**: `pytest` +- **Location**: `tests/` directory +- **Commands**: + - `uv run pytest tests/path/to/tests` to run a specific test file or folder. + - `make test` - Run all tests. + - `make test-integration` - Run integration tests. +- **Best Practice**: Always include tests with new features. + +### Linting & Formatting +- You can delegate to the `lint` agent in `.github/agents` to resolve linting issues. +- **Tools**: + - `ruff` - Formatting and linting. + - `mypy` - Static type checking. +- **Commands**: + - `make lint` - Check for issues. + - `make format` - Auto-format code. +- **Requirement**: All code must be fully type-annotated. + +### CLI +- **Framework**: Built with `typer`. +- **Location**: `plugboard/cli/`. +- **Usage**: `plugboard --help`. + +## Code Standards + +### Async Pattern +- Entire framework built on `asyncio`. +- All I/O operations must be async. +- All component lifecycle methods must be async. + +### Dependency Injection +- Uses `that-depends` for DI. +- Container setup: `plugboard/utils/DI.py`. +- Access logger: `self._logger = DI.logger.resolve_sync().bind(...)`. + +### Data Structures +- Prefer immutable structures: `msgspec.Struct(frozen=True)`. +- Use Pydantic models for validation where needed. + +### Components +When creating components: +1. Inherit from `plugboard.component.Component`. +2. Always call `super().__init__()` in `__init__`. +3. Declare I/O via class-level `io` attribute. +4. Implement required async methods. +5. Use type hints throughout. + +Example: +```python +import typing as _t +from plugboard.component import Component, IOController as IO +from plugboard.schemas import ComponentArgsDict + +class MyComponent(Component): + io = IO(inputs=["input_a"], outputs=["output_x"]) + + def __init__( + self, + param: float = 1.0, + **kwargs: _t.Unpack[ComponentArgsDict] + ) -> None: + super().__init__(**kwargs) + self._param = param + + async def step(self) -> None: + # Business logic here + self.output_x = self.input_a * self._param +``` + +### Events +- Event system for component communication. +- Define events by inheriting from `plugboard.events.Event`. +- Add handlers with `@Event.handler` decorator. +- Emit events via `self.io.queue_event()` or return from handlers. + +## Best Practices + +1. **Minimal Changes**: Make surgical, focused changes. +2. **Type Safety**: Maintain full type annotations. +3. **Testing**: Add tests for new functionality. +4. **Documentation**: Update docstrings and docs for public APIs. You can delegate to the `docs` agent in `.github/agents` to maintain the project documentation. +5. **Async Discipline**: Never use blocking I/O operations. +6. **Immutability**: Prefer immutable data structures. +7. **Logging**: Use structured logging via `structlog`. +8. **Error Handling**: Use appropriate exception types from `plugboard.exceptions`. + +## Common Tasks + +### Adding a New Component +1. Create class inheriting from `Component`. +2. Define `io` with inputs/outputs. +3. Implement `__init__` with proper signature. +4. Implement async `step` method. +5. Add tests in `tests/`. +6. Update documentation if public API. + +### Modifying Core Framework +1. Understand impact on existing components. +2. Ensure backward compatibility where possible. +3. Update type stubs if needed. +4. Run full test suite. +5. Update relevant documentation. + +### Working with Events +1. Define event class with data model. +2. Declare in component's `io` (input_events/output_events). +3. Implement handlers with decorators. +4. Use `EventConnectorBuilder` for wiring. + +## Online Resources + +- **Repository**: https://github.com/plugboard-dev/plugboard +- **Documentation**: https://docs.plugboard.dev +- **Issue Tracker**: GitHub Issues +- **Discussions**: GitHub Discussions