AI Model Configuration
HitKeep can use an optional AI model for features that need structured summarization or recommendation copy. The first 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.
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, 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 |
| 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 A Region-Scoped Provider
Section titled “Setup With A Region-Scoped Provider”Some providers require a region or platform profile. Configure the provider’s own environment first, then set the HitKeep provider/model fields.
HITKEEP_AI_ENABLED=trueHITKEEP_AI_PROVIDER=bedrockHITKEEP_AI_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0AWS_REGION=eu-central-1AWS_ACCESS_KEY_ID=...AWS_SECRET_ACCESS_KEY=...HITKEEP_AI_REQUEST_LIMIT=100HITKEEP_AI_TOKEN_LIMIT=100000HITKEEP_AI_BUDGET_WINDOW=1440Use 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 | The current Opportunities enrichment request expects a compact JSON object and 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. |