OSDP Prototype

Quick start 🚀

Prerequisites

To get started you will need to have the following installed:

• uv (installation instructions)
• aws cli (installation instructions)
• AWS cdk cli (see install instructions))

Note

If you don't have uv installed (or don't want to), see alternate instructions below.

Install

Install dependencies in a virtual environment:

uv sync --all-groups

Activate the virtual environment:

source .venv/bin/activate

While logged into aws, verify that it will build:

cd osdp && cdk synth -c stack_prefix=my-awesome-stack

Important

If cdk cannot locate the python deps, restarting your shell will typically fix it.

Deploy

Run the deploy command with a required stack_prefix:

cd osdp && cdk deploy -c stack_prefix=my-awesome-stack

Install uv with Python

To install uv locally

Ensure you are using Python 3.10:

python --version
# Python 3.10.5

Create a virtual environment:

python -m venv .venv

Activate it:

source .venv/bin/activate

Install uv within the virutual environment:

pip install uv

Install dependencies:

uv sync --all-groups

Development 🛠️

IIIF manifest fetcher docker image

This is a ECR repository that is consumed by the OSDP.

See its readme for more information.

OSDP Prototype Stack (CDK)

Setup

The OSDP primarily uses Python, but NodeJS is used for one lambda.

Python

Follow the steps in the quickstart

Tip

If using VSCode, set your Python interpreter by opening the Command Palette ⇧⌘P and choosing Python: Select Interpreter. Set the path to ./.venv/bin/python. Read more here.

Node

Ensure using v22:

node --version
# v22.13.1

There is one lambda that uses node:

cd functions/build_function
npm i
cd ../../

Define context values

Context values are key-value pairs that can be associated with an app, stack, or construct. They may be supplied in the cdk.json or or on the command line.

Since the cdk.json file is generally committed to source control, it should generally be used for values shared with the team. Anything that needs to be overriden with specific deploys should be supplied on theh command line.

Required context values

• stack_prefix (str) - will be appended to the beginning of the CloudFormation stack on deploy. (*For NU devs this is not needed, it will use the DEV_PREFIX env var in AWS.)
• collection_url (str)- the url of the IIIF collection to load during deployment. There is a small collection (6 items) in the cdk.json file, but you will want to change or override on the command line.
• embedding_model_arn (str) - Embedding model to use for Bedrock Knowledgebase
• foundation_model_arn (str) - Foundation model to use for Bedrock RetreiveAndGenerate invocations

Optional context values

• tags (dict) - Key value pair tags applied to all resources in the stack. Example:

"tags": {
      "project": "chatbot"
    },

• manifest_fetch_url (str) - The concurrency to use when retrieving IIIF manifests from your API. If not provided, the default will be used (2).

# use default secret name (`OSDPSecrets`)
cdk deploy

Providing context values on the command line

Example:

cdk deploy -c stack_prefix=alice

Synthesize the CloudFormation template (optional)

Synthesize the CloudFormation template for this code (login to AWS account first). You must first log in to AWS with administrator credentials.

cdk synth

Deploy the CDK app

To deploy the stack to AWS. You must first log in to AWS with administrator credentials using aws sso login.

First obtain your stack name. Ex:

cdk ls

yourprefix-OSDP-Prototype #this one is your stack name
OsdpPipelineStack
OsdpPipelineStack/staging/OSDP-Prototype (staging-OSDP-Prototype)

Then deploy your stack:

cdk deploy yourprefix-OSDP-Prototype

Testing

To run the tests.

pytest

If the app has not been synthesized, tests may fail. See synth instructions.

Linting

ruff check .

or

ruff check --fix .

Style

To run formatting

ruff format .

Useful commands

Useful cdk commands to be run within the osdp/ directory:

• cdk ls list all stacks in the app
• cdk synth emits the synthesized CloudFormation template
• cdk deploy deploy this stack to your default AWS account/region
• cdk diff compare deployed stack with current state
• cdk docs open CDK documentation

Enjoy!