AI Model Configuration
HitKeep can use an optional AI model for features that need structured summarization or recommendation copy. The first saved-output feature is Opportunity Recommendations.
AI is off by default. HitKeep Cloud manages the model route for cloud customers. Self-hosted operators choose the HitKeep provider/model route and local budget settings through HITKEEP_AI_* variables. Provider credentials are resolved by the wrapped goAI provider, so set the provider’s own environment variables for keys, base URLs, or platform credentials unless you are using a HitKeep-specific override.
What The Model Does
Section titled “What The Model Does”For Opportunity Recommendations, HitKeep does not ask the model to discover facts from scratch. HitKeep reads aggregate analytics first, runs deterministic detectors, and then asks the model for a small structured response.
The model may choose:
- approved title, summary, action, and digest translation keys
- allowed interpolation params for those keys
- cited evidence IDs from the detector output
- small metadata fields such as action type and effort
The model may not create new evidence, make unsupported source claims, write free-form customer prose, expose raw prompts, or add financial promises. HitKeep validates the structured response before saving it.
Cloud And Self-Hosted Behavior
Section titled “Cloud And Self-Hosted Behavior”| Deployment | Who configures the model | What the customer sees |
|---|---|---|
| HitKeep Cloud | HitKeep operates the provider/model route and budget policy. | System Status can show non-secret state, provider/model labels when exposed, usage, caps, and safe error categories. |
| Self-hosted | The instance operator sets the HitKeep route/budget fields and the selected goAI provider’s credential environment. | The same System Status fields are available without exposing secrets. |
| AI disabled | No provider call is made. | Detector-backed Opportunities can still be generated when the feature has enough aggregate evidence. |
Choose A Model
Section titled “Choose A Model”Choose a model for reliable structured output, not marketing copy. A good model route for HitKeep should be fast, cost-controlled, and strong at JSON schema following.
Useful model traits:
- supports structured output or consistently returns valid JSON
- handles short analytical instructions without adding prose
- has enough context for aggregate evidence snapshots
- reports token usage when possible
- has latency and cost that fit scheduled recommendation generation
- can be pinned to the deployment region or gateway policy you need
HitKeep does not require one provider. You can use any provider supported by the HitKeep goAI wrapper, an OpenAI-compatible gateway, a region-scoped provider, or a local model if it can pass validation.
For AWS-credit-friendly self-hosted deployments, the recommended default route is OpenAI GPT OSS 120b through the Amazon Bedrock Mantle OpenAI-compatible endpoint:
HITKEEP_AI_PROVIDER=openai-compatibleHITKEEP_AI_MODEL=openai.gpt-oss-120bHITKEEP_AI_BASE_URL=https://bedrock-mantle.<region>.api.aws/v1HITKEEP_AI_REGION=<region>
Mantle keeps the OpenAI-compatible request shape while routing inference through AWS billing and Bedrock access controls. HitKeep signs Mantle requests with the EC2 instance or task role when no explicit HITKEEP_AI_API_KEY is set, so production cloud deployments do not need a static Bedrock bearer token.
Direct Amazon Bedrock remains supported through HITKEEP_AI_PROVIDER=bedrock. Use amazon.nova-lite-v1:0 for a lower-cost direct Bedrock model, or amazon.nova-pro-v1:0 when you want stronger Amazon Nova responses through Bedrock Converse.
Bedrock’s Converse API supports tool configuration, and Amazon Bedrock tool use is client-side for the common case: the model asks for a tool, then the application executes it and sends the result back. HitKeep uses that client-side pattern for direct Bedrock models. With Mantle, HitKeep uses the same local tool loop through goAI’s OpenAI-compatible path, so all analytics tools still run inside HitKeep’s permission and aggregate-data boundary.
Anthropic models on Bedrock can be a stronger option when schema/tool reliability matters more than cost. Current Bedrock model cards list anthropic.claude-haiku-4-5-20251001-v1:0 and anthropic.claude-sonnet-4-5-20250929-v1:0 with Converse support. Model access, Marketplace subscription, regional availability, or cross-region inference setup may be required in your AWS account.
HitKeep Environment Variables
Section titled “HitKeep Environment Variables”Set these on the HitKeep process. Values can also be passed as matching CLI flags. Keep provider secrets in your process manager, container secret store, or cloud secret manager.
| Environment variable | Default | Required when | Meaning |
|---|---|---|---|
HITKEEP_AI_ENABLED | false | Always, to enable AI | Enables optional AI-assisted features. |
HITKEEP_AI_PROVIDER | "" | AI enabled | Provider key used by HitKeep’s goAI wrapper. Common choices include openai, openai-compatible, bedrock, litellm, bifrost, gateway, anthropic, google, mistral, openrouter, groq, and ollama. |
HITKEEP_AI_MODEL | "" | AI enabled | Provider-specific model ID or gateway route name. |
HITKEEP_AI_BASE_URL | "" | OpenAI-compatible routes | Gateway or custom endpoint base URL. Required for openai-compatible, compat, gateway, bifrost, and litellm. For direct providers, prefer the provider’s goAI base URL variable such as OPENAI_BASE_URL. |
HITKEEP_AI_REGION | "" | Optional override | Region override passed to providers that support it. For AWS Bedrock, goAI also reads AWS_REGION or AWS_DEFAULT_REGION. |
HITKEEP_AI_API_KEY | "" | Optional override | Static token passed to goAI providers that support WithAPIKey or bearer-token options. Prefer provider-native variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY. Redacted in logs and status. |
HITKEEP_AI_TIMEOUT_SECONDS | 30 | Optional | Provider request timeout. |
HITKEEP_AI_REQUEST_LIMIT | 100 | Optional | Maximum AI requests per budget window. 0 disables the local request cap. |
HITKEEP_AI_TOKEN_LIMIT | 100000 | Optional | Maximum counted provider tokens per budget window. 0 disables the local token cap. |
HITKEEP_AI_BUDGET_WINDOW | 1440 | Optional | Budget window in minutes. The default is one day. |
Provider Credential Environment
Section titled “Provider Credential Environment”HitKeep does not rename every provider’s credential variables. It builds the selected goAI provider and lets that provider resolve its documented environment variables. Use the goAI supported providers documentation as the source of truth for provider-specific auth variables, base URL overrides, and provider pages.
Common variables are:
| Provider | Environment variables goAI reads |
|---|---|
| OpenAI | OPENAI_API_KEY, optional OPENAI_BASE_URL |
| Anthropic | ANTHROPIC_API_KEY, optional ANTHROPIC_BASE_URL |
| Google Gemini | GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY, optional GOOGLE_GENERATIVE_AI_BASE_URL |
| Bedrock Mantle | EC2/task role or AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, plus HITKEEP_AI_REGION or AWS_REGION. Optional HITKEEP_AI_API_KEY for a temporary bearer-token override. |
| AWS Bedrock | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION or AWS_DEFAULT_REGION, optional AWS_BEARER_TOKEN_BEDROCK and AWS_BEDROCK_BASE_URL |
| OpenRouter | OPENROUTER_API_KEY |
| Mistral | MISTRAL_API_KEY, optional MISTRAL_BASE_URL |
| Groq | GROQ_API_KEY |
| xAI | XAI_API_KEY, optional XAI_BASE_URL |
| Cohere | COHERE_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY, optional DEEPSEEK_BASE_URL |
| Fireworks | FIREWORKS_API_KEY, optional FIREWORKS_BASE_URL |
| Together | TOGETHER_AI_API_KEY or TOGETHER_API_KEY |
| Perplexity | PERPLEXITY_API_KEY |
| Cerebras | CEREBRAS_API_KEY, optional CEREBRAS_BASE_URL |
Check the goAI provider documentation for the exact provider you select. If you set HITKEEP_AI_API_KEY, HitKeep passes it as an explicit option and it can override provider env resolution for providers that support static keys.
Setup With A Direct Provider
Section titled “Setup With A Direct Provider”Use this when HitKeep should call the provider directly. Set the HitKeep route fields plus the provider’s goAI credential environment.
HITKEEP_AI_ENABLED=trueHITKEEP_AI_PROVIDER=openaiHITKEEP_AI_MODEL=your-json-capable-modelOPENAI_API_KEY=provider_key_from_your_secret_storeHITKEEP_AI_REQUEST_LIMIT=100HITKEEP_AI_TOKEN_LIMIT=100000HITKEEP_AI_BUDGET_WINDOW=1440Replace openai and your-json-capable-model with the provider and model you want to use. See the Configuration Reference for the supported provider keys.
Setup With An AI Gateway
Section titled “Setup With An AI Gateway”Use this when an internal gateway owns routing, provider choice, policy, and billing.
HITKEEP_AI_ENABLED=trueHITKEEP_AI_PROVIDER=openai-compatibleHITKEEP_AI_MODEL=opportunities-jsonHITKEEP_AI_BASE_URL=https://ai-gateway.example.com/v1HITKEEP_AI_REQUEST_LIMIT=100HITKEEP_AI_TOKEN_LIMIT=100000HITKEEP_AI_BUDGET_WINDOW=1440The gateway can route opportunities-json to any model it supports. Authentication is optional for the generic goAI-compatible provider. If your gateway expects a bearer token, set HITKEEP_AI_API_KEY as an explicit gateway token. HitKeep still validates output locally and still enforces its local request and token budgets before provider calls.
Setup With Bedrock Mantle
Section titled “Setup With Bedrock Mantle”Use this for the default AWS-billed GPT OSS route. On EC2, ECS, or another AWS runtime, prefer an instance or task role that can call Bedrock. Set HITKEEP_AI_REGION so HitKeep can sign Mantle requests for the right region.
HITKEEP_AI_ENABLED=trueHITKEEP_AI_PROVIDER=openai-compatibleHITKEEP_AI_MODEL=openai.gpt-oss-120bHITKEEP_AI_BASE_URL=https://bedrock-mantle.eu-central-1.api.aws/v1HITKEEP_AI_REGION=eu-central-1HITKEEP_AI_REQUEST_LIMIT=100HITKEEP_AI_TOKEN_LIMIT=100000HITKEEP_AI_BUDGET_WINDOW=1440For local smoke tests with a temporary Bedrock bearer token, export AWS_BEARER_TOKEN_BEDROCK into your shell and pass it through as HITKEEP_AI_API_KEY only for that process. Production should normally use IAM role credentials and SigV4 signing instead of a static token.
Setup With Direct Amazon Bedrock
Section titled “Setup With Direct Amazon Bedrock”Use this when you want inference to run through AWS account billing and IAM. Configure AWS credentials or an instance/task role that can call Bedrock Runtime, enable model access in Bedrock as required, then set the HitKeep provider/model fields.
HITKEEP_AI_ENABLED=trueHITKEEP_AI_PROVIDER=bedrockHITKEEP_AI_MODEL=amazon.nova-lite-v1:0AWS_REGION=eu-central-1AWS_ACCESS_KEY_ID=...AWS_SECRET_ACCESS_KEY=...HITKEEP_AI_REQUEST_LIMIT=100HITKEEP_AI_TOKEN_LIMIT=100000HITKEEP_AI_BUDGET_WINDOW=1440For stronger responses, use amazon.nova-pro-v1:0. For Anthropic-on-Bedrock, use a model ID such as anthropic.claude-haiku-4-5-20251001-v1:0 or anthropic.claude-sonnet-4-5-20250929-v1:0 after your AWS account has the required model access.
AWS announced that Activate credits can be redeemed for third-party models on Amazon Bedrock. AWS Billing documentation says eligible credits are applied automatically to eligible service charges until they are exhausted or expire. HitKeep does not decide credit eligibility, sharing, expiration, or which linked account consumes credits. Confirm the AWS billing account, credit sharing settings, Bedrock model access, and current Bedrock pricing before enabling this on a production self-hosted instance.
Useful AWS references:
- Amazon Bedrock tool use
- Amazon Bedrock Converse API
- Amazon Nova tool use
- AWS Activate credits for third-party Bedrock models
- Applying AWS credits
Use HITKEEP_AI_REGION only when you want HitKeep to pass an explicit region override to a provider that supports it.
Setup With A Local Model
Section titled “Setup With A Local Model”Local models are useful for development and offline checks. They are not automatically release-quality for customer-facing recommendations. Use a model that can return strict JSON reliably.
HITKEEP_AI_ENABLED=trueHITKEEP_AI_PROVIDER=ollamaHITKEEP_AI_MODEL=llama3.1HITKEEP_AI_BASE_URL=http://127.0.0.1:11434If validation fails, HitKeep keeps detector-backed output and records a safe invalid_output category.
Token Limits
Section titled “Token Limits”HITKEEP_AI_TOKEN_LIMIT is a local usage budget. It is not the model context window and it is not the per-response output cap.
Three different limits can apply:
| Limit | Owner | Meaning |
|---|---|---|
| Model context window | Provider or gateway | Maximum input plus output size the model can handle. |
| Provider output cap | HitKeep request and provider | Opportunities asks for at most 900 output tokens. |
| Local token budget | HitKeep | Maximum counted provider tokens per HITKEEP_AI_BUDGET_WINDOW. |
Start with a small budget and raise it after System Status shows normal usage.
| Use case | Suggested request limit | Suggested token limit | Window |
|---|---|---|---|
| Small self-hosted instance | 20 | 50000 | 1440 |
| Medium self-hosted instance | 100 | 100000 | 1440 |
| Active smoke testing | 80 | 240000 | 60 |
| Disabled provider calls | Leave HITKEEP_AI_ENABLED=false | Leave default | Leave default |
Request limits count provider calls. Token limits count usage reported by the provider or gateway. Some providers may omit token usage for failed calls or tool steps, so keep upstream provider limits as a second guardrail.
Set either local cap to 0 only when another enforced system owns the same limit.
Verify System Status
Section titled “Verify System Status”The Administration -> System Status page and /api/admin/system/ai endpoint show non-secret AI status:
- enabled/configured state
- provider and model label
self_hostedorcloud_managedconfiguration mode- request and token usage in the current budget window
- cap state, including budget exhaustion
- last safe success or error category
Status never returns provider secrets, raw prompts, raw provider responses, raw external error bodies, or unrestricted tool output.
Audit And Storage Boundary
Section titled “Audit And Storage Boundary”AI run records keep the operational facts needed for audit:
- team, site, actor, and feature
- provider and model label
- prompt template version
- cited evidence IDs
- input and output hashes
- final validated structured output
- request and token usage when available
- lifecycle events for request and tool start/finish, latency, status, and safe error category
HitKeep does not persist raw prompts or raw provider payloads. For Opportunities, public API, MCP, share links, takeout, and email digests use the saved customer-visible output, not raw model text.
Troubleshooting
Section titled “Troubleshooting”| Status or symptom | What to check |
|---|---|
disabled | HITKEEP_AI_ENABLED is false or missing. Deterministic Opportunity detectors can still run. |
not_configured | Provider/model is missing, provider is unsupported, or an OpenAI-compatible provider is missing HITKEEP_AI_BASE_URL. |
budget_exhausted | Raise HITKEEP_AI_REQUEST_LIMIT, raise HITKEEP_AI_TOKEN_LIMIT, shorten the generation window, or wait for the HITKEEP_AI_BUDGET_WINDOW to reset. |
auth_failed | Check the selected goAI provider’s environment variables, platform credentials, provider model access, region, and gateway token policy. |
rate_limited | Lower generation frequency or raise provider/gateway quotas. |
timeout | Increase HITKEEP_AI_TIMEOUT_SECONDS, reduce gateway latency, or use a faster model route. |
invalid_output | Use a model with better structured-output support or route through a gateway/model profile tuned for JSON schema compliance. |