Install the basics, request GitHub access, and check repo rules before writing code.
2 Learn the basicsUse the Learn page for Git, terminal, Poetry, and Streamlit basics. For custom apps, follow the React/FastAPI template README.
3 Test on devTest locally first, then verify AI and platform behavior on dev.
4 Request dev deploySubmit your use case in Requirements Agent and obtain approval before dev deployment. Push ready code to main and include the All requests PRD link in your deployment request.
The stack
What you need before you start, what you build on, and what is already installed.
Site access on Mac
- Open the ERM self-service catalog.
- Search for CloudFlare Certificate.
- Click Install.
- Reopen your browser and try the AI Marketplace again.
- If the certificate is not listed or does not install, email [email protected].
Before you start
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.
| Tool | How to install |
|---|---|
| Python 3.14.2 | Open the ERM self-service catalog, search for Python, and click Install. |
| Poetry | pip install poetry (after Python is installed) |
| Git | Open the ERM self-service catalog, search for Git, and click Install. |
| An editor or IDE | Open 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.
Opens an email template for your IT Service Desk ticket.
|
- Choose the app type before creating the repo. All new Streamlit and custom React/FastAPI repositories must use
ai-marketplace-<your-app-name>. Existingcapability-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.
| Component | Detail |
|---|---|
| Language | Python 3.14.2 |
| UI framework | Streamlit 1.x, or React + FastAPI for custom apps |
| Dependency manager | Poetry (not pip) |
| Entry point | Streamlit: app.py at the repo root. Custom apps: backend/server.py plus frontend/. |
| Template | Streamlit: 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.
| Package | What you use it for |
|---|---|
streamlit | UI framework (pages, widgets, layout, file upload, download) |
pandas | Tabular data manipulation, CSV/Excel read/write |
boto3 | AWS SDK, available for explicitly configured AWS services |
anthropic | Platform 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"}
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)
| Need | Options | Guidance |
|---|---|---|
| Instructions and chat | system_prompt, messages | Keep permanent instructions in system_prompt; use messages only for conversation history. |
| Files and images | documents, images | Pass raw bytes and a format. Images require an admin-selected OpenAI GPT-5.6 model. |
| Reliable JSON | response_schema | Prefer a strict JSON Schema over asking for JSON only in the prompt, then parse the returned text with json.loads. |
| Operational controls | max_tokens, timeout_seconds, on_usage | Set a realistic output limit and timeout. Use the callback to record token and cache usage without logging prompts. |
| Repeated large context | prompt_cache, prompt_cache_ttl | Use 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.
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.
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.
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
| Step | Where | What to prove |
|---|---|---|
| 1. Build and test locally | Your laptop | Streamlit: 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 main | GitHub | The 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 deploy | ai-marketplace-dev.ermtools.app | Submit 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 dev | Use realistic inputs and exercise the whole app. If it uses AI, choose one of the AI testing routes below. |
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.
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.
After you submit
| Point | Detail |
|---|---|
| Timing | Allow 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 URL | https://ai-marketplace-dev.ermtools.app/<your-tool>/ — available after your first dev deploy. Dev is where you iterate. |
| Success story | After 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 promotion | Once dev is stable, use the Dev to prod checklist below and send a short prod promotion request to the admin. |
| Verifying it landed | Compare 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.
| Step | Where | What to prove |
|---|---|---|
| 1. Confirm the dev build | ai-marketplace-dev.ermtools.app | Use 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 ownership | Your team | Make sure the app owner accepts the build, understands the support responsibility, and is ready for ERM users to open it. |
| 3. Request prod deploy | ai-marketplace.ermtools.app | Use the prod promotion request form below. It includes the required confirmations before the admin promotes the app. |
| 4. Verify on prod | /your-tool/ on prod | Open 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 story | Stories page | Once 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.
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 write | Why |
|---|---|
| Dockerfile | Platform builds your image. Do not add app-owned Dockerfiles or deployment scripts. |
| Framework runtime config | For 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 / SSO | Platform 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 / domain | The platform owns ai-marketplace.ermtools.app, ai-marketplace-dev.ermtools.app, and their routing. |
| Landing-page card | Generated automatically when your tool is registered |
| CI/CD | Platform 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
| Problem | Solution |
|---|---|
poetry: command not found | pip install poetry, then restart your terminal |
Address already in use on port 8501 or 5173 | Close the other local app, or run Streamlit/FastAPI/Vite on a different port using the command options in the relevant template README. |
ModuleNotFoundError | poetry add <package> — never pip install |
Deploy fails with pyproject.toml changed significantly since poetry.lock was last generated | You 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 error | Use 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 rejected | git 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 click | Expected. 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 state | Planned 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. |