convez.ai
MCP ServerDados & AnalyticsAvançado
redhat-ai-americas

FBI UCR Crime Forecasting Demo

redhat-ai-americas/fbi-ucr-demo

Demo completa: LLM + previsão de crimes + MCP server + agente em OpenShift

Ver no GitHub
InicialPluginScore · de 0 a 100

Demonstração repetivelOpenShift que implementa um sistema completo de previsão de crimes com LLM (gpt-oss-20b), modelos de séries temporais (Prophet/ARIMA) e um agente de análise criado via MCP server. Integra dados do FBI UCR com interface chat em ~30-40 minutos.

Instalação

$npx convez-ai redhat-ai-americas/fbi-ucr-demo

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Demonstrações técnicas de arquitetura LLM + MCP em ambiente empresarial
  • Análise preditiva de dados criminais com modelos de séries temporais
  • Prototipagem rápida de agentes que consultam APIs externas via MCP

Veredito

Demonstração técnica sólida que integra LLM de código aberto, MCP server e modelos preditivos em OpenShift. Excelente para aprender arquitetura de agentes em produção, mas requer cluster Kubernetes e experiência com DevOps.

README

A tradução para o português deste README ainda está na fila.

FBI UCR Crime Forecasting Demo

A repeatable OpenShift demo that stands up:

  1. gpt-oss-20b — vLLM-served LLM with tool-calling support (GPU)
  2. FBI UCR predictive service — Prophet/ARIMA models for 5 offenses × national + 5 states
  3. FBI Crime Stats MCP server — exposes ucr_forecast, ucr_history, ucr_compare, ucr_info tools
  4. Crime analyst agent — fipsagents BaseAgent wired to the MCP server and the LLM
  5. Gateway — fips-agents API gateway in front of the agent (anonymous auth, /v1/* proxy)
  6. Chat UI — fips-agents web UI talking to the gateway

End-to-end runtime: ~30–40 minutes from logged-in cluster to working chat UI.


Prerequisites

  • A fresh OpenShift 4 cluster (see Cluster sizing below)
  • Local tools: oc, ansible (with the kubernetes.core collection), helm, git, bash
  • An FBI Crime Data Explorer API key (free, ~30 sec) — required for the ucr_history tool. The other three tools (ucr_forecast, ucr_compare, ucr_info) work without it.
pip install ansible kubernetes
ansible-galaxy collection install kubernetes.core

Getting an FBI API key

  1. Visit https://api.data.gov/signup/ and submit your email.
  2. The key arrives by email immediately (one-line value, ~40 chars).
  3. Pass it to setup.sh (see below) — it's stored in a Kubernetes Secret in the fbi-mcp namespace and read by the MCP server's ucr_history tool.

Without a key, ucr_history returns a clear 403 API_KEY_MISSING error to the agent, which surfaces it to the user. Forecasts (ucr_forecast, ucr_compare, ucr_info) still work — they hit the in-cluster predictive service, not the public FBI API.


Get a cluster

Order an OCP4 Sandbox from the Red Hat Demo System:

catalog.demo.redhat.com — sandboxes-gpte.sandbox-ocp.prod

Cluster sizing

SettingValue
Control plane nodes3
Control plane instance typem6a.xlarge
Worker nodes3
Worker instance typem6a.4xlarge

The demo automation creates a separate GPU MachineSet (g6e.4xlarge, NVIDIA L40S) at deploy time — you don't need to add GPU workers up front.

Provisioning takes ~45–60 minutes.


Run the demo

Once the cluster is up, log in as kubeadmin (credentials are in the demo system order page):

oc login --server=https://api.cluster-XXXXX.sandbox-ocp.opentlc.com:6443 \
         --username=kubeadmin --password=<from-order-page>

Then from the repo root, with your FBI API key:

./setup.sh --fbi-api-key YOUR_FBI_KEY_HERE

(You can omit --fbi-api-key if you don't plan to use the ucr_history tool — see prereqs.)

That's it. The script:

  1. Generates an Ansible inventory from your active oc context (no cluster_list.txt needed for single-cluster demos).
  2. Runs ansible/site.yml — installs NFD + NVIDIA GPU operator + RHOAI 3.3, creates the GPU MachineSet, waits for nvidia.com/gpu capacity (~15–20 min).
  3. Runs ansible/fbi-deploy.yml — deploys gpt-oss-20b, predictive service, MCP server (built from upstream Git), and the chatbot agent (~10–15 min).
  4. Prints the routes for everything at the end.

Optional flags

./setup.sh --fbi-api-key YOUR_KEY        # Required for ucr_history; optional for the rest
./setup.sh --enable-htpasswd             # Workshop mode: requires you to provide your own auth/*.yaml manifests
./setup.sh --no-gpu                      # CPU-only (skips LLM serving)
./setup.sh --skip-cluster-setup          # Cluster already has RHOAI + GPU
./setup.sh --agent-local /path/to/agent  # Use a local agent repo (dev mode)
./setup.sh --oc-context fbi-ucr          # Pin to a specific oc context (multi-session safety)

Adding the FBI API key after the fact

If you ran setup.sh without --fbi-api-key and the user hits 403 API_KEY_MISSING from ucr_history, patch the Secret and roll the pod:

oc --context=fbi-ucr -n fbi-mcp patch secret fbi-crime-stats-mcp-secrets \
  --type=merge -p '{"stringData":{"FBI_API_KEY":"YOUR_KEY_HERE"}}'
oc --context=fbi-ucr -n fbi-mcp rollout restart deployment/fbi-crime-stats-mcp
oc --context=fbi-ucr -n fbi-agent rollout restart deployment/fbi-crime-analyst-agent

The agent restart is needed so it re-establishes its MCP session against the rebuilt server.


What gets deployed

WorkloadNamespaceImage / Source
gpt-oss-20b (vLLM)gpt-oss-modelregistry.redhat.io/rhaiis/vllm-cuda-rhel9:3 serving RedHatAI/gpt-oss-20b
Predictive servicefbi-ucrquay.io/wjackson/crime-stats-api:latest
MCP serverfbi-mcpBuildConfig from fbi-crime-stats-mcp
Agentfbi-agentBuildConfig from fbi-crime-analyst-agent
Gatewayfbi-gatewayBuildConfig from fbi-crime-analyst-gateway
UIfbi-uiBuildConfig from fbi-crime-analyst-ui

Source repos are pinned in ansible/group_vars/all.yml — change them in one place when the upstream repos move.


Repo layout

.
├── setup.sh                  # one-shot entry point
├── scripts/
│   ├── generate_inventory.sh    # turn `oc whoami` into ansible inventory
│   └── deploy-fips-component.sh # generic agent/gateway/UI deploy via on-cluster BuildConfig + helm
├── ansible/
│   ├── site.yml              # cluster bring-up (NFD + GPU + RHOAI)
│   ├── fbi-deploy.yml        # FBI workloads
│   ├── group_vars/all.yml    # all knobs
│   └── roles/workshop_cluster/...  # 10-phase cluster setup role
├── operators/                # Subscription manifests (NFD, GPU, RHOAI)
├── operands/                 # DataScienceCluster, NFDInstance
├── gpu-operand/              # NVIDIA ClusterPolicy
├── namespaces/               # operator namespaces
├── auth/                     # HTPasswd OAuth (only used with --enable-htpasswd)
├── model/                    # gpt-oss-20b vLLM serving
└── manifests/
    ├── predictive-service/   # ns + deployment + service + route
    └── mcp-server/           # ns + deployment + service + route (BuildConfig is inline in fbi-deploy.yml)

Provenance

The cluster bring-up automation (ansible/, operators/, operands/, gpu-operand/, namespaces/, auth/, model/gpt-oss-20b.yaml) is vendored from redhat-ai-americas/openshift-ai-workshop-setup (or wherever workshop-setup lives at vendoring time). Cluster-prep changes that aren't FBI-specific should go upstream there first.

The chatbot agent's system prompt is the canonical version maintained in fbi-crime-stats-mcp/system_prompts/fbi_crime_analyst_system_prompt.md. The agent repo vendors a copy.


Troubleshooting

See docs/troubleshooting.md.

Ver o original no GitHub

Bom para

Relacionados