Developer Guide

Build an AI Marketplace app

What you write, what the platform gives you, and how your tool gets to production. For consultants using the Streamlit template or the custom React/FastAPI template.

Back to tools
First time here? The guide below assumes you already know basic Python, Git, and the app template you are using. If Streamlit, Git, or terminal commands sound unfamiliar, start at Learn — a set of ready-to-paste prompts for Microsoft Copilot that will catch you up in under an hour.
Start at Learn

The stack

What you need before you start, what you build on, and what is already installed.

Site access on Mac

Required before anything else If you are on an ERM Mac, install the CloudFlare Certificate before trying to open the AI Marketplace or any deployed tool URL. Without it, the site may not load at all.
  1. Open the ERM self-service catalog.
  2. Search for CloudFlare Certificate.
  3. Click Install.
  4. Reopen your browser and try the AI Marketplace again.
  5. If the certificate is not listed or does not install, email [email protected].

Before you start

Note You do not need to be a developer to build a tool here, but a little technical familiarity helps you get started — things like running a command in a terminal, cloning a repo, or reading an error message. AI tools like Copilot will walk you through most of the rest. If you have never written code at all, first try the Requirements Agent or Copilot to see if they can solve your use case before building a tool here.

Install these once on your machine. Python, Git, and Visual Studio Code should already be in your ERM self-service catalog and install automatically with no approval required. If one of those apps is missing from your catalog, raise a Technology Support request.

ToolHow to install
Python 3.14.2Open the ERM self-service catalog, search for Python, and click Install.
Poetrypip install poetry (after Python is installed)
GitOpen the ERM self-service catalog, search for Git, and click Install.
An editor or IDEOpen the ERM self-service catalog, search for Visual Studio Code, and click Install. PyCharm, Cursor, or any other editor you already use is also fine.
GitHub access Membership in the ERMInc GitHub org. GitHub Copilot can be requested in the same GitHub access ticket. Share this direct link with anyone who needs access: GitHub access request instructions.
GitHub Copilot
Opens an email template for your IT Service Desk ticket.
Repository and marketplace rules
  • Choose the app type before creating the repo. All new Streamlit and custom React/FastAPI repositories must use ai-marketplace-<your-app-name>. Existing capability-tool-* repos are legacy-supported; do not use that prefix for new apps.
  • Set the repo to internal, not private. Platform admin needs access to register and troubleshoot deploys.
  • Do not put confidential data, client data, credentials, secrets, or restricted information in your GitHub repo, code, config files, or sample data. If your app will process client confidential or sensitive data, review the AI security and client data guidance before proceeding.
  • Apps listed in the AI Marketplace can be seen by everyone at ERM. Restricted-use apps are not supported there yet; contact the platform admin if you need that feature logged.
  • The platform does not review your PRs or app logic; reviewing and testing your code is your responsibility.

Stack at a glance

Most consultant apps are Streamlit. Use the custom React/FastAPI template only when the app needs a richer UI, protected API routes, file processing, or workflow control beyond Streamlit. The platform handles deployment around both app types.

Streamlit framework versus hosted service This guide describes the open-source Streamlit framework packaged inside an ERM AI Marketplace-hosted app. It is not approval to use Streamlit Community Cloud or another standalone Streamlit service, and each Marketplace app remains subject to its own data, security, testing, and deployment requirements. Read the plain-English explanation and Service Desk response.
ComponentDetail
LanguagePython 3.14.2
UI frameworkStreamlit 1.x, or React + FastAPI for custom apps
Dependency managerPoetry (not pip)
Entry pointStreamlit: app.py at the repo root. Custom apps: backend/server.py plus frontend/.
TemplateStreamlit: ERMInc/capability-tool-template retains its legacy name; new app repos created from it must use ai-marketplace-<name>. Custom: ERMInc/ai-marketplace-custom-app-template. Use "Use this template" on GitHub.

Pre-installed libraries

These are already available. Import them directly. For anything else, run poetry add <package> — never pip install, never hand-edit pyproject.toml.

PackageWhat you use it for
streamlitUI framework (pages, widgets, layout, file upload, download)
pandasTabular data manipulation, CSV/Excel read/write
boto3AWS SDK, available for explicitly configured AWS services
anthropicPlatform dependency only. Consultant apps should not call Anthropic/OpenAI directly or ask users for API keys; use call_llm (section 3) so AI calls go through ERM Bedrock.

Writing your app

The required sign-in pattern, the platform AI helper, and a pointer to Streamlit basics when you need widget or state examples.

Require ERM sign-in

Every app must cooperate with platform SSO before showing workflows or reading uploaded data. The exact code depends on the app type.

Streamlit apps call require_login() near the top of app.py. Do not hide it behind a deployed fallback: if the deployed entrypoint does not include this guard, users see a developer action required message instead of the app.

import streamlit as st
from platform_config import require_login

require_login()

st.title("My AI Marketplace app")

Custom React/FastAPI apps keep the SSO contract from ERMInc/ai-marketplace-custom-app-template: React calls /api/session before showing workflows, and every non-health FastAPI route uses require_user_dependency or require_user(request).

from fastapi import Depends

from .capability_platform import User, require_user_dependency


@api.post("/review")
async def review(user: User = Depends(require_user_dependency)):
    return {"status": "ok"}
Required Streamlit apps must keep the guard in the committed app.py entrypoint. Custom React/FastAPI apps must keep /api/session protected and reject protected routes without ALB OIDC identity when ALB_OIDC_REQUIRED=true.

The call_llm helper

The platform ships one stable helper for AI calls. The deployment selects the approved model; application code does not pass model IDs or provider API keys. This keeps the same app code working when an admin changes its model tier. In Streamlit, call it from app.py; in custom React/FastAPI apps, call it from FastAPI, never directly from React.

from platform_config import call_llm

answer = call_llm("Summarize this text: " + user_input)
st.write(answer)

Use keyword arguments only when the workflow needs them. Existing prompt-only calls remain supported.

import json

answer = call_llm(
    "Review the supplied document and return the requested fields.",
    max_tokens=1200,
    system_prompt="You are a careful environmental risk reviewer.",
    documents=[{"format": "pdf", "bytes": uploaded_file.getvalue()}],
    response_schema={
        "type": "object",
        "properties": {
            "summary": {"type": "string"},
            "risk_level": {"type": "string"},
        },
        "required": ["summary", "risk_level"],
        "additionalProperties": False,
    },
    timeout_seconds=120,
)

# call_llm always returns text; structured output is JSON text.
result = json.loads(answer)
NeedOptionsGuidance
Instructions and chatsystem_prompt, messagesKeep permanent instructions in system_prompt; use messages only for conversation history.
Files and imagesdocuments, imagesPass raw bytes and a format. Images require an admin-selected OpenAI GPT-5.6 model.
Reliable JSONresponse_schemaPrefer a strict JSON Schema over asking for JSON only in the prompt, then parse the returned text with json.loads.
Operational controlsmax_tokens, timeout_seconds, on_usageSet a realistic output limit and timeout. Use the callback to record token and cache usage without logging prompts.
Repeated large contextprompt_cache, prompt_cache_ttlUse only for stable, repeated context after measuring cost and latency. GPT-5.6 uses a 30-minute cache.

OpenAI GPT-5.6 Luna in dev

An admin can opt a specific dev app into the dev_strong tier, which currently selects openai.gpt-5.6-luna. The application still imports the same call_llm function. Luna adds image input, function tools, verbosity, and per-call reasoning controls:

answer = call_llm(
    "Analyse the trade-offs and recommend an action.",
    reasoning_effort="low",       # none, low, medium, high, xhigh, or max
    verbosity="low",              # low, medium, or high
    timeout_seconds=180,
)

The deployment default for dev_strong is low, but the app may override effort per call when a task needs more or less reasoning. Do not pass temperature for GPT-5.6; use reasoning effort and verbosity. Function tools are available through tools and tool_handler, with max_tool_rounds providing a bounded loop.

Privacy and model access Response storage is off by default. Do not set store=True unless the workflow has an approved need for Bedrock's 30-day response retention; previous_response_id requires storage. Use a non-personal pseudonymous value for safety_identifier. Consultants cannot switch models from application code: admins assign app tiers in platform deployment configuration, production remains on its approved default, and dev_strong is dev-only.
Note call_llm needs platform AWS access. For the testing order, follow Local to dev. The controlled local role supports Nova Micro only; test dev_strong Luna in an admin-configured dev deployment. Do not use personal Anthropic or OpenAI API keys for platform apps.
Need Streamlit basics? Components, common widgets, copyable patterns, and state/rerun guidance now live on the Learn page so this guide can stay focused on platform setup and deployment.
Open Streamlit basics

Running and shipping

Two phases: first get a working dev deployment, then promote that stable build to prod.

Local to dev

Use this phase while building. Local testing proves your app code and data handling. Dev proves the platform pieces: ERM sign-in, routing, container permissions, and call_llm.

poetry install
poetry run streamlit run app.py
StepWhereWhat to prove
1. Build and test locallyYour laptopStreamlit: run poetry run streamlit run app.py. Custom React/FastAPI: run the backend and frontend commands from the template README. Test layout, parsing, exports, charts, API routes, and custom logic before asking for dev.
2. Push ready code to mainGitHubThe platform deploy pipeline pulls from the main branch only. Pushing does not auto-deploy; the platform pulls your latest main the next time an admin triggers a deploy. Commit poetry.lock with any pyproject.toml change.
3. Request dev deployai-marketplace-dev.ermtools.appSubmit your use case in Requirements Agent and obtain approval before dev deployment. Include the submitted PRD link from All requests when asking the admin for a dev deploy. First-time apps are added to the platform registry before deployment. Dev validates ERM sign-in, final URL routing, platform container behavior, and call_llm.
4. Verify full flow on dev/your-tool/ on devUse realistic inputs and exercise the whole app. If it uses AI, choose one of the AI testing routes below.
AI testing If your app uses call_llm, the normal route is to test the UI locally, deploy to dev, then test the full AI flow on dev. Local AI testing is optional and only needed when you must call Bedrock from your laptop before deployment. This is an interim path while a more streamlined local AI testing setup is being worked on.

Test AI on dev

Use when

This is the standard route for most apps.

Steps
  1. Build and test the app locally. For Streamlit, test the UI in Streamlit. For custom React/FastAPI, test both the React frontend and FastAPI backend.
  2. Ask for a dev deploy.
  3. Test the full AI flow on ai-marketplace-dev.ermtools.app.

On dev, call_llm uses the platform container role, so you do not need separate ERM privileged access for AWS.

Test AI locally

Use when

You need to run call_llm from your laptop before deployment.

Steps
  1. Submit the ERM IT - Privileged Account Request Form. Account creation usually takes 1-2 days.
  2. Send the ERM email address that should have AWS access to [email protected]. It will be added to CapabilityDevLLMTesters; allow up to 40 minutes to sync.
  3. Open the AWS access portal and sign in with your ERM account. Then test locally.

If AWS access still does not work, test the AI flow on dev. If the account does not appear in AWS after about 40 minutes, ask IT to check that First Name, Last Name, and Email are populated.

Submitting a dev deploy request

Before dev deployment, submit your use case in Requirements Agent for review and obtain approval. Include the submitted PRD link from All requests. Sending this deployment request does not grant approval: deployment will not take place until the use case has been approved. Deploys are admin-triggered. Fill in the form and click submit — it opens your email client with a pre-filled message to the platform admin. Prod promotion is covered in the Dev to prod section below.

AI Marketplace · Dev deploy request Mockup
App type
Streamlit apps use ERMInc/capability-tool-template; all new repos must use ai-marketplace-<name>, for example ai-marketplace-survey-analyzer.
@erm.com
So the admin can reply when your tool is live.
Needed to grant access to ERM's GitHub if you aren't already a member.
Lowercase, hyphen-separated. Enter sample-id-checker; if you paste capability-tool-sample-id-checker or ai-marketplace-sample-id-checker, the form removes the duplicate prefix.
We'll create: https://github.com/ERMInc/ai-marketplace-<your-name>
The pipeline pulls main only — make sure main contains exactly what you want shipped (this is not a code review).
One sentence — shown on the landing page card.
Pick one or more — filter categories on the landing page.
Open your submitted PRD in All requests and copy its page URL. Include the request page link, not a downloaded PRD or download link.

After you submit

PointDetail
TimingAllow 1 working day after the use case is approved and a complete deployment request is received. Same for updates. The pipeline itself takes around 15 minutes once the admin triggers it.
Your dev URLhttps://ai-marketplace-dev.ermtools.app/<your-tool>/ — available after your first dev deploy. Dev is where you iterate.
Success storyAfter the app is working in dev, use the Capture a success story form to record what the app can do and the early value seen so far.
Prod promotionOnce dev is stable, use the Dev to prod checklist below and send a short prod promotion request to the admin.
Verifying it landedCompare the platform's deployment timestamp against the time you submitted. If the latest deployment is after your submission and your app looks unchanged, check that your changes were on main before you submitted.

Dev to prod

Use this phase only after dev is stable. Prod is for apps that are ready for real users.

StepWhereWhat to prove
1. Confirm the dev buildai-marketplace-dev.ermtools.appUse the deployed dev URL and verify the full workflow with realistic inputs. Fix issues on main and redeploy to dev until it is stable.
2. Confirm ownershipYour teamMake sure the app owner accepts the build, understands the support responsibility, and is ready for ERM users to open it.
3. Request prod deployai-marketplace.ermtools.appUse the prod promotion request form below. It includes the required confirmations before the admin promotes the app.
4. Verify on prod/your-tool/ on prodOpen the prod URL after deployment and do a quick smoke test: page loads, sign-in works, key workflow works, and any app card links are correct.
5. Capture the storyStories pageOnce the app is deployed to dev or prod, capture a short success story so the platform value and app capability are visible.

Submitting a prod promotion request

Use this only after the dev app works as desired. The confirmations are required because prod apps and marketplace cards are visible to all ERM users.

Prod promotion is blocked if the app has no working SSO, shows a local/dev fallback in deployed mode, allows access when the user identity is missing, asks users to paste external AI API keys, or calls Anthropic/OpenAI directly instead of the ERM Bedrock platform helper.

AI Marketplace · Prod promotion request Mockup
App type
Choose the same app type used for the dev deployment request.
@erm.com
The person confirming the app is ready for prod and responsible after launch.
Paste the exact dev URL you tested and approved. The app name is read from this URL.
All confirmations must be checked before the email opens. For client confidential or sensitive data, review AI security and client data guidance first.
Optional, but useful if there is anything the admin should know before promotion.

What the platform handles

The platform owns the infrastructure around your app. You should not add any of these to your repo.

You do not writeWhy
DockerfilePlatform builds your image. Do not add app-owned Dockerfiles or deployment scripts.
Framework runtime configFor Streamlit, the platform applies the ERM theme and runtime config. For custom React/FastAPI apps, use the template's base-path-aware frontend and FastAPI entrypoint.
Auth / SSOPlatform fronts every tool with ERM sign-in. Streamlit apps still call require_login() near the top of app.py. Custom React/FastAPI apps call /api/session before showing workflows and protect every non-health FastAPI route with require_user_dependency or require_user(request).
HTTPS / domainThe platform owns ai-marketplace.ermtools.app, ai-marketplace-dev.ermtools.app, and their routing.
Landing-page cardGenerated automatically when your tool is registered
CI/CDPlatform clones your repo, builds the Docker image, and deploys — but today the pipeline has to be triggered by a platform admin (see Planned enhancements for self-service CI/CD plans)

Reference

What to check when things go wrong.

Troubleshooting

ProblemSolution
poetry: command not foundpip install poetry, then restart your terminal
Address already in use on port 8501 or 5173Close the other local app, or run Streamlit/FastAPI/Vite on a different port using the command options in the relevant template README.
ModuleNotFoundErrorpoetry add <package> — never pip install
Deploy fails with pyproject.toml changed significantly since poetry.lock was last generatedYou changed pyproject.toml without re-running poetry lock. Run poetry lock, git add poetry.lock, commit, push, ask for a redeploy.
call_llm fails locally with a credentials errorUse the dev environment for AI testing, or follow the local AI testing option in the flow. If AWS access does not appear within about 40 minutes after setup, ask IT to check that First Name, Last Name, and Email are populated.
git push rejectedgit pull first, resolve any conflicts, push again
Site does not load after deploy (Mac)Cloudflare certificate missing. Open the ERM self-service catalog, search for CloudFlare Certificate, and click Install. If the certificate is not listed or does not install, email [email protected].
Widgets reset on every clickExpected. Persist values with st.session_state; see State and reruns on the Learn page.

Planned enhancements

These are platform improvements being worked on. They are not required steps for your current app build.

Current statePlanned enhancement
Every deploy — to dev and to prod — has to be triggered by a platform admin. Pushing to your repo does not ship your code on its own.Self-service CI/CD per repo: push your ai-marketplace-<name> repo and your tool deploys to dev, with a controlled route to prod. Existing capability-tool-* repos remain legacy-supported.
Every admin-triggered deploy rebuilds every app in the platform, which takes around 15 minutes end to end.Single-app deploys under 5 minutes using change detection and Docker layer caching.
Local call_llm testing currently needs interim AWS access setup. Most apps should test AI after a dev deploy.A more streamlined local AI testing route so consultants can validate Bedrock behavior without the current manual AWS access steps.
Consultant-facing app storage is not yet a standard self-service path.S3-backed storage support, including a simpler request path and standard setup for files, exports, and structured JSON.
You install Python, Poetry, and Git yourself before you can start.Single installer bundling all prerequisites, so non-technical users can get set up in one click.