Interpretos Local — Administrator Guide

> Version: 2026.1.104 | Last Updated: 2026-03-12

Overview

Interpretos Local is an AI copilot for enterprise applications. It connects to Oracle E-Business Suite, PeopleSoft, and IBM Maximo and lets users query their systems using natural language.

This guide covers everything an administrator needs to install, configure, operate, and extend their Interpretos Local instance. It also serves as the knowledge base for the built-in Admin Assistant ("Need help?" button).

Setup Wizard

On first launch, a 6-step wizard guides you through initial configuration. After completing the AI Model Provider step (Step 2), a "Need help?" button appears — click it to chat with an AI assistant that can answer questions about any setup step in real time.

Step 0: License Key

Choose one of three paths:

Step 1: Admin Account

Create the first administrator account.

Step 2: AI Model Provider

Choose the LLM that powers your chat experience. This is the fast model — used for simple queries like lookups and detail views.

For self-hosted models, provide the base URL (e.g., http://localhost:11434/v1 for Ollama).

Click Test Connection to verify before proceeding.

Smart Model (Recommended)

For BYOK providers (Google, OpenAI, Anthropic, Custom), a "Add a Smart Model" panel appears below the fast model configuration.

What it does: Simple queries (lookups, details) use the fast model above. Complex queries (analytics, dashboards, multi-table joins) need a frontier model for accurate results. The system automatically routes each query to the right model based on complexity.

Configuration:

How auto-routing works: The RAG (pattern selection) step assesses query complexity. Simple entity lookups stay on the fast model. Analytical, multi-entity, or aggregation queries are automatically upgraded to the smart model. Users see this as seamless — the right model is chosen per query.

Smart model quota: To control costs, smart model usage is limited to 30 queries per user per day (configurable in Admin Panel > Settings). When the quota is exhausted, queries fall back to the fast model.

Interpretos Cloud users get automatic fast/smart routing — no configuration needed.

Step 3: Integration Connections

Connect to your enterprise systems. You can configure one or more integrations.

Oracle E-Business Suite (EBS)

Direct Database Mode (recommended — 1-3 second queries):

SSH Tunnel Mode (11-17 second queries):

Common issues:

PeopleSoft

Connects via SSH tunnel to Oracle database (no direct mode).

PeopleSoft uses CDB/PDB architecture. The PDB name is critical — it's set via ALTER SESSION SET CONTAINER before any query. If you're unsure, ask your DBA for the PDB name or run SELECT name FROM v$pdbs on the CDB.

IBM Maximo

Connects via REST API (OSLC interface).

Common issues:

Step 4: Telemetry (Optional)

Enable anonymous aggregate metrics to help improve the product.

Step 5: Review and Complete

Summary of all settings. Click Complete Setup to finish. A security recommendations panel reminds you to enable TLS and set a secret key for production.

Admin Panel

Access the admin panel by clicking the gear icon in the header bar. The "Need help?" button in the top-right corner opens the AI-powered Admin Assistant — it can answer questions about any panel, setting, or configuration task.

Users Tab

Manage system users and their roles.

Adding users:

User actions:

Roles:

Admin users skip the per-user RBAC login prompt and query using the global admin credentials configured during setup.

Credentials Tab

Map each user to their identity in each enterprise system. This controls what data they see through role-based access control (RBAC).

How RBAC works: When user "jsmith" sends a chat query, Interpretos uses jsmith's personal credentials (not the admin's) to query the enterprise system. If jsmith's Oracle account is restricted to the BEDFORD site, they'll only see BEDFORD data. Admin users bypass this — they always use the global admin credentials and see all data.

Setting credentials:

If no per-user credentials are set, the user inherits the global admin connection — meaning they see ALL data. For security, configure per-user credentials for restricted users.

Credential fields by integration:

API Keys Tab

Generate programmatic API keys for automation, bots, and integrations.

Creating a key:

Using API keys:

# Via X-API-Key header
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ik_your_key_here" \
  -d '{"message": "How many open work orders are there?"}'

# Via Authorization header
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ik_your_key_here" \
  -d '{"message": "Show me overdue POs"}'

Full API documentation is available at /api/docs (interactive Swagger UI).

Settings Tab

AI Provider Settings

Change the primary (fast) LLM provider after setup. Same options as setup step 2. Always test before saving.

Extra Parameters: Optional JSON object passed directly to the chat LLM API call. Use this for provider-specific tuning:

Model Options for Users (Fast / Smart / Auto)

Configure model presets that users can switch between during chat. Up to 3 presets can be defined.

Preset roles:

How it works:

Smart model quota: Limits smart model usage to a configurable number of queries per user per day (default: 30). When exhausted, queries fall back to the fast model. Configure the limit via PUT /api/admin/smart-quota or the Admin Panel.

Click the "Model Options for Users" section header to expand, configure presets, test each one, and save.

Pattern Selection LLM (Advanced)

Configure an optional separate, faster LLM for pattern selection (the step that picks which knowledge pattern to use before answering).

Click the "Pattern Selection LLM" section header to expand, enable the checkbox, configure, test, and save.

Extra Parameters: Optional JSON object passed directly to the LLM API call. Use this for provider-specific tuning without code changes:

Pattern selection doesn't need reasoning/thinking — it's a simple pattern-matching task. If using a model with built-in thinking (Gemini 3 Flash, GPT-5.4 Thinking), disable it here for dramatically faster responses (26s to 2s in testing).

Integration Connection Settings

Update EBS, PeopleSoft, or Maximo connection settings. Same fields as setup step 3.

Custom Instructions

Set admin-wide default context for all users on a specific integration.

Examples:

Select the integration from the dropdown, write instructions (max 1000 characters), and save. Users can also set their own personal instructions via the Preferences button in the chat header.

Restart Setup Wizard

Re-runs the guided setup. Preserves your license and user accounts but lets you reconfigure AI provider and integration connections.

Patterns Tab

Create custom patterns to teach the chatbot queries specific to your environment. Custom patterns extend the built-in knowledge without affecting it. Custom patterns are encrypted at rest on the persistent data volume.

Creating a Pattern

Click + New Pattern and fill in:

Click Save Pattern. The chatbot immediately starts using the new pattern — no restart needed. Pattern IDs are auto-generated from the description.

Testing a Pattern

Click Test on any pattern, enter a sample question, and click Run Test. The system sends the query through the full chatbot pipeline and shows:

Managing Patterns

Backup and Migration

Custom patterns are stored on the persistent data volume (/app/data/custom_patterns/) and survive container restarts and upgrades.

Updates Tab

Check for and install updates.

License Tab

View and manage your product license.

Diagnostics Tab

Health monitoring, debugging, and audit trail for compliance.

System Health

Click Test All Connections to validate every configured service (LLM provider, databases, APIs). Green/red indicators show what's working.

Debug Logging

Toggle between INFO (normal) and DEBUG (verbose) log levels. Enable DEBUG when troubleshooting specific issues, then disable it — verbose logs consume more disk space.

LLM Capture & Replay

Record and replay LLM API calls for debugging chatbot behavior.

Enable capture: Toggle LLM call recording on. Every LLM request/response is saved to disk.

View captured calls: Browse recent calls filtered by type (chat, RAG, etc.). Each captured call shows the full request (messages, model, parameters) and response.

Replay a call: Re-send a captured request to the LLM and compare the new response with the original. Useful for debugging non-deterministic behavior or testing model changes.

Configuration: Set maximum file size and number of captured files to manage disk usage.

Endpoints: GET /api/admin/llm-capture/status, POST /api/admin/llm-capture/toggle, PUT /api/admin/llm-capture/configure, GET /api/admin/llm-capture/calls, GET /api/admin/llm-capture/calls/{id}, POST /api/admin/llm-capture/replay/{id}

Recent Errors

View recent server errors with timestamps, details, and stack traces. Useful for diagnosing connection failures or LLM errors.

Telemetry

Query Audit Log

Every query sent to connected enterprise systems is logged here — SQL statements for EBS/PeopleSoft, API calls for Maximo. Stored at /app/data/query_audit.jsonl.

Use this for: security audits, compliance reviews, debugging incorrect query results, and understanding what the AI is actually asking your systems.

Support Bundle

Download a diagnostic package to attach to support tickets. This bundle is privacy-safe: it excludes credentials, SQL text, conversation content, and usernames. It contains system info, connectivity results, error summaries, and anonymized metrics.

User Features

These features are available to all authenticated users (not just admins).

Model Switching

Users can switch between model presets configured by the admin:

The active preset persists across sessions. Switch via the model selector in the chat header.

Personal Custom Instructions

Users can set their own custom instructions via the Preferences button in the chat header. These are appended to the admin-wide custom instructions. Max 1000 characters.

Example: "I work in the BEDFORD site, always filter results to BEDFORD unless I say otherwise."

Conversations

EBS/PeopleSoft Login (RBAC)

For EBS and PeopleSoft integrations with per-user credentials configured, users see a login bar at the top of the chat. They enter their enterprise username and password to establish their RBAC context. This ensures queries run with their credentials, not the admin's.

Admin users do not see this login bar — they always use the global credentials.

Password Change

Users can change their own password via the user menu in the header.

Demo Mode

When DEMO_MODE=true is set as an environment variable, the instance operates in demo mode for public evaluation.

Demo registration flow:

Demo account limits:

Automatic cleanup: a background thread removes expired demo users every 60 seconds, preserving analytics data (email, organization, query count, conversations used).

Environment variables:

REST API Reference

Interpretos Local exposes a full REST API. Interactive documentation is available at /api/docs (Swagger UI) and the OpenAPI spec at /api/docs/openapi.yaml.

Authentication

Two methods:

Core Endpoints

OpenAI-Compatible API

Interpretos Local exposes an OpenAI-compatible API, allowing any tool or platform that supports OpenAI (such as [Sana](https://sana.ai), LangChain, or custom scripts) to use Interpretos as a drop-in AI provider.

Quick Start

from openai import OpenAI

client = OpenAI(
    base_url="https://your-interpretos-host:8080/v1",
    api_key="ik_...",  # Your Interpretos API key
)

response = client.chat.completions.create(
    model="interpretos-auto",
    messages=[{"role": "user", "content": "What are the top 5 assets by cost?"}],
)
print(response.choices[0].message.content)

Endpoints

Available Models

Authentication

Use your Interpretos API key (created in Admin Panel > API Keys) as the Bearer token. The OpenAI SDK sends this automatically when you set api_key.

Streaming

Streaming is supported (stream: true). The chatbot processes the full query and returns the complete response in a single chunk, followed by [DONE].

Third-Party Platform Configuration

When connecting Interpretos to platforms like Sana, configure:

Notes

User Endpoints

Admin Endpoints

Admin Assistant Endpoints

Demo Endpoints (DEMO_MODE only)

Bulk Provisioning

For enterprise deployments, use the bulk endpoints to create users and assign credentials in batch.

Bulk user creation (POST /api/admin/users/bulk):

{
  "users": [
    {
      "username": "jsmith",
      "password": "Welcome123!",
      "display_name": "Jane Smith",
      "role": "user",
      "credentials": {
        "oracle_ebs": {
          "EBS_DB_USER": "JSMITH",
          "EBS_DB_PASSWORD": "...",
          "EBS_DB_SERVICE": "VIS"
        }
      }
    }
  ],
  "update_existing": false
}

Response includes created, updated, skipped, and errors counts. Max 500 users per request.

Bulk credential assignment (POST /api/admin/credentials/bulk):

{
  "assignments": [
    {
      "username": "jsmith",
      "integration_id": "oracle_ebs",
      "credentials": {
        "EBS_DB_USER": "JSMITH",
        "EBS_DB_PASSWORD": "...",
        "EBS_DB_SERVICE": "VIS"
      }
    }
  ]
}

Max 500 assignments per request.

Advanced Configuration

Environment Variables

These environment variables can be set on the Docker container to override settings.

LLM Provider

Pattern Selection LLM (overrides UI settings)

Oracle EBS

PeopleSoft

Maximo

System

Override precedence: Environment variable > UI/setup wizard setting > default value.

RAG Configuration

Advanced RAG behavior can be tuned via /app/config/rag_config.yaml. Most admins will not need to modify this file — the defaults work well for all supported integrations.

Key settings:

Configuration Files

Automation Cookbook

These recipes show how to use the REST API to automate common administrative tasks. All examples use Python with the requests library.

1. Bulk User Creation from CSV

import csv
import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key", "Content-Type": "application/json"}

with open("users.csv") as f:
    for row in csv.DictReader(f):  # columns: username, display_name, password, role
        resp = requests.post(f"{BASE}/api/admin/users", headers=HEADERS, json={
            "username": row["username"],
            "display_name": row["display_name"],
            "password": row["password"],
            "role": row.get("role", "user")
        })
        print(f"{row['username']}: {resp.json().get('status', resp.status_code)}")

CSV format:

username,display_name,password,role
jsmith,Jane Smith,Welcome123!,user
mbrown,Mike Brown,Welcome123!,user
admin2,Senior Admin,SecurePass!,admin

For large deployments (50+ users), use the bulk endpoint instead:

import csv
import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key", "Content-Type": "application/json"}

users = []
with open("users.csv") as f:
    for row in csv.DictReader(f):
        users.append({
            "username": row["username"],
            "display_name": row["display_name"],
            "password": row["password"],
            "role": row.get("role", "user")
        })

resp = requests.post(f"{BASE}/api/admin/users/bulk", headers=HEADERS, json={
    "users": users,
    "update_existing": False
})
result = resp.json()
print(f"Created: {result['created']}, Skipped: {result['skipped']}, Errors: {len(result['errors'])}")

2. Bulk Credential Assignment

import csv
import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key", "Content-Type": "application/json"}

with open("credentials.csv") as f:
    for row in csv.DictReader(f):  # columns: username, db_user, db_password, ...
        resp = requests.put(
            f"{BASE}/api/users/{row['username']}/credentials/oracle_ebs",
            headers=HEADERS,
            json={
                "EBS_DB_USER": row["db_user"],
                "EBS_DB_PASSWORD": row["db_password"],
                "EBS_DB_SERVICE": row.get("db_service", "VIS"),
                "username": row.get("ebs_username", row["username"])
            }
        )
        print(f"{row['username']}: {resp.json().get('status', resp.status_code)}")

3. Automated Health Monitoring

import requests
import smtplib
from email.mime.text import MIMEText

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key"}

# Check health
health = requests.get(f"{BASE}/api/health")
if health.status_code != 200:
    # Send alert email
    msg = MIMEText(f"Interpretos health check failed: {health.status_code}")
    msg["Subject"] = "ALERT: Interpretos Down"
    msg["From"] = "monitoring@company.com"
    msg["To"] = "admin@company.com"
    with smtplib.SMTP("smtp.company.com") as s:
        s.send_message(msg)

# Test all connections
conns = requests.post(f"{BASE}/api/admin/diagnostics/test-connections", headers=HEADERS)
for result in conns.json().get("results", []):
    if result.get("status") != "ok":
        print(f"FAILED: {result['name']} - {result.get('error', 'unknown')}")

4. Scheduled Daily Report

import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_reports_user_key", "Content-Type": "application/json"}

questions = [
    "How many purchase orders were approved this week?",
    "Show me the top 5 vendors by PO spend this month",
    "Are there any overdue work orders?"
]

for q in questions:
    resp = requests.post(f"{BASE}/api/chat", headers=HEADERS, json={"message": q})
    data = resp.json()
    print(f"\nQ: {q}")
    print(f"A: {data.get('response', data.get('message', 'No response'))}")

# Reset conversation for next run
requests.post(f"{BASE}/api/reset", headers=HEADERS)

5. User Offboarding Script

import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key"}

username = "departing_user"
resp = requests.delete(f"{BASE}/api/admin/users/{username}", headers=HEADERS)
print(f"Deleted {username}: {resp.json()}")
# This removes the user account, all their credentials, API keys, and chat history

6. Custom Pattern via API

import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key", "Content-Type": "application/json"}

# Create a custom pattern for EBS employee lookup
resp = requests.post(f"{BASE}/api/admin/patterns/custom", headers=HEADERS, json={
    "integration": "oracle_ebs",
    "description": "Employee lookup by employee number",
    "query_type": "sql",
    "query": "SELECT employee_number, full_name, email_address FROM per_all_people_f WHERE employee_number = :emp_num AND SYSDATE BETWEEN effective_start_date AND effective_end_date",
    "example_questions": ["Who is employee 12345?", "Show employee details for 67890"],
    "entity_types": ["employee", "person", "hr"],
    "tables": ["PER_ALL_PEOPLE_F"]
})
print(f"Created: {resp.json()['pattern']['pattern_id']}")

# Export all patterns for backup
resp = requests.get(f"{BASE}/api/admin/patterns/custom/export", headers=HEADERS)
with open("patterns_backup.json", "w") as f:
    f.write(resp.text)
print(f"Exported {resp.json()['count']} patterns")

7. Export Query Audit for Compliance

import requests
import json

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key"}

# Get query audit log
audit = requests.get(f"{BASE}/api/admin/audit/queries", headers=HEADERS)
entries = audit.json().get("entries", [])

# Write to file for compliance archive
with open(f"query_audit_export.jsonl", "w") as f:
    for entry in entries:
        f.write(json.dumps(entry) + "\n")

print(f"Exported {len(entries)} audit entries")

8. Smart Quota Management

import requests

BASE = "http://localhost:8080"
HEADERS = {"X-API-Key": "ik_your_admin_key", "Content-Type": "application/json"}

# Check current quota and usage
resp = requests.get(f"{BASE}/api/admin/smart-quota", headers=HEADERS)
data = resp.json()
print(f"Daily limit: {data['daily_limit']}")
for user, count in data.get('usage', {}).items():
    print(f"  {user}: {count}/{data['daily_limit']} smart queries today")

# Increase the limit
requests.put(f"{BASE}/api/admin/smart-quota", headers=HEADERS, json={"daily_limit": 50})

Security Recommendations

Database Credentials

SSH Keys

Network Security

Maximo API Keys

RBAC Best Practices

API Key Management

Sensitive Data

Troubleshooting

EBS: "SSH connection failed"

EBS: "ORA-12154: TNS could not resolve connect identifier"

EBS: "ORA-01017: invalid username/password"

PeopleSoft: "ORA-65024: ALTER SESSION SET CONTAINER not allowed"

PeopleSoft: "PDB not found"

Maximo: "401 Unauthorized"

Maximo: "Connection refused" or "timeout"

LLM: "API key not valid"

LLM: "Model not found"

Slow responses

Smart model quota exhausted

Admin assistant not responding

Documentation Links

*Interpretos Local is developed by Code Development Limited. For support, visit interpretos.ai.*