pl8-base

pl8-base is the data layer for PL8, a lightweight issue tracker for AI agents and the people working alongside them, backed by DynamoDB. It's a Python library, not a service: it defines PL8's entities (Issue, Space, IssueBlocker), its events, and the BasePL8 manager that reads and writes them against a DynamoDB table. It's the source of truth for PL8's data model, consumed by the Lambda functions that actually run PL8 in AWS.

To use PL8, you don't need this library. Deploy PL8 to your own AWS account and use it through pl8-cli; see the setup and usage guides. pl8-base is for working on PL8 itself.

Status: alpha (0.0.x). Interfaces may change between releases.

Getting started

Install

pip install pl8-base

or with uv:

uv add pl8-base

Basic usage

BasePL8 wraps a boto3 DynamoDB client and a structured logger. Error logging passes arbitrary keyword args through to be merged into the log record (e.g. self.logger.error(msg, item=item)), which a stdlib logging.Logger rejects — pass an aws-lambda-powertools Logger instead (pip install aws-lambda-powertools — it's not a dependency of this package, since only your logger instance needs it, not pl8-base itself). It also expects a table already provisioned with PK/SK and a GSI1 global secondary index (GSI1PK/GSI1SK) — see Deploying below.

import boto3
from aws_lambda_powertools import Logger

from pl8_base.manager import BasePL8
from pl8_base.types import IssueStatus

pl8 = BasePL8(
    dynamodb_client=boto3.client("dynamodb"),
    table_name="pl8",
    logger=Logger(),
)

space = pl8.create_space(
    space_id="eng",
    name="Engineering",
    description="Issues for the engineering team",
)

issue = pl8.create_issue(
    space_id="eng",
    title="Fix login bug",
    description="Users can't log in on Safari",
    status=IssueStatus.TODO,
)

pl8.transition_issue(space_id="eng", issue_id=issue.issue_id,
                     status=IssueStatus.IN_PROGRESS)

Rules

BasePL8 enforces PL8's entity rules and raises an error from pl8_base.errors when a call breaks one:

Retrying one of these unchanged won't help. DDBTransactionConflictError is different: it means contention that BasePL8 already retried, nothing was applied, and the same call can be retried. The full rules are in Entities.

Some updates happen in the background rather than in the call that caused them, such as moving a blocked Issue back to TODO when its last blocker finishes. The handle_* methods apply them, driven by the DynamoDB stream and events that pl8-services wires up; see Events.

Deploying

pl8-base only talks to a DynamoDB table you already have; it doesn't provision or run anything in AWS itself. pl8-services provisions the table, event bus and queues, and runs the Lambdas that use this library. See the setup guide to deploy it.

Repositories

Contributing

See CONTRIBUTING.md.

License

MIT