Interpretos Local — Administrator Guide

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.

Setup Wizard

On first launch, a 6-step wizard guides you through initial configuration.

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.

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

Click Test Connection to verify before proceeding.

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.

Admin Panel

Access the admin panel by clicking the gear icon in the header bar. Eight tabs provide full administrative control.

Users Tab

Manage system users and their roles.

Adding users:

User actions:

Roles:

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.

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 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:

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.

Creating a Pattern

Click + New Pattern and fill in:

Click Save Pattern. The chatbot immediately starts using the new pattern — no restart needed.

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.

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.

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

Admin Endpoints

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

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")

Security Recommendations

Database Credentials

SSH Keys

Network Security

Maximo API Keys

RBAC Best Practices

API Key Management

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

Documentation Links

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