Interpretos Manual

Getting Started

Interpretos Local runs as a Docker container on your infrastructure. All configuration happens in your browser through a setup wizard — no environment variables or config files needed.

Prerequisites

• Docker and Docker Compose installed on your machine
• Credentials for your target system (see integration-specific requirements below)

Installation

Create a file called docker-compose.yml in an empty directory:

services:
  interpretos-local:
    image: interpretos/local:latest
    ports:
      - "8080:5000"
    volumes:
      - interpretos-data:/app/data
    restart: unless-stopped

volumes:
  interpretos-data:

Start the container:

docker compose up -d

Open http://localhost:8080 in your browser to begin the setup wizard.

Setup Wizard

On first launch, the wizard walks you through five steps:

For detailed per-integration setup steps with example queries, see the Quickstart Guide.

Admin Guide

The Admin Panel is accessible by clicking the gear icon in the top-right corner of the chat interface. Only users with the admin role can access it.

AI Provider Settings

Change your AI provider at any time from Admin Panel > Settings > AI Provider.

Use the Test Connection button to verify your key before saving.

Integration Settings

Modify your database or API connection settings from Admin Panel > Settings. Each integration has its own configuration section.

User Management

Manage user accounts from Admin Panel > Users.

Per-User Credentials & RBAC

By default, all users share the global credentials configured in the setup wizard. For row-level access control, you can give each user their own credentials so they only see data they're authorized for.

Why per-user credentials?

In a real deployment, different people need different access levels. A finance analyst should only see their operating unit's data, not the entire company. A site maintenance planner should only see their site's work orders.

How to set it up

1. Go to Admin Panel > Users and create user accounts
2. Go to Admin Panel > Credentials
3. Select a user and an integration (e.g. Oracle EBS)
4. Enter that user's own database credentials or API key
5. Save — when this user chats, their queries will use their credentials

How it works per integration

• Oracle EBS: Users log in with their EBS username and password via the EBS Login bar in the chat UI. Queries are automatically filtered to their authorized operating units, ledgers, and organizations.
• IBM Maximo: Each user can have their own API key. The Maximo server enforces security groups, so different keys see different data.
• PeopleSoft: Each user can have their own database credentials, enforcing PeopleSoft's row-level security via department profiles.

Custom Instructions (Admin)

Custom instructions let you tailor the AI assistant's behavior for your organization. Admin-level instructions apply to all users of a specific integration.

Configure them at Admin Panel > Settings > Custom Instructions. Select an integration (e.g. Oracle EBS), then enter your instructions.

What to put here

• Organization-specific terminology — "When users say 'budget', they mean the GL net period activity (period_net_dr minus period_net_cr)"
• Default filters — "Always filter EBS queries to operating unit 204 unless the user specifies otherwise"
• Naming conventions — "Our Maximo site codes are: BEDFORD, NASHUA, AUSTIN. Users may refer to these as 'Bedford plant', 'NH site', or 'Texas'"
• Response formatting preferences — "Always show monetary values in USD with two decimal places"
• Domain context — "We are a discrete manufacturing company. When users ask about 'jobs', they mean work orders, not HR positions"

Example

## Organization Defaults

Our Maximo instance covers three sites:
- BEDFORD (primary manufacturing)
- NASHUA (warehouse and distribution)
- AUSTIN (R&D lab)

Terminology:
- "PM" means Preventive Maintenance, not Project Manager
- "WO" means Work Order
- "The plant" refers to BEDFORD unless stated otherwise

When showing costs, always include the work order description
alongside the cost figure for context.

Telemetry

Interpretos can optionally send anonymous usage metrics to help us improve the product. Telemetry is disabled by default and requires explicit opt-in during setup or in the Admin Panel.

What is collected (when enabled)

• Random instance ID (no IP address, no hostname)
• Query count per day
• Module used (e.g. PO, AP, GL)
• Success/failure counts
• Response time

What is never collected

• Query text or SQL statements
• Database hostnames, usernames, or credentials
• IP addresses
• Any data from your enterprise systems

You can inspect exactly what will be transmitted before it leaves your network at Admin Panel > Audit Log > Telemetry > Preview.

Audit Log

Every query that Interpretos executes against your systems is logged with full detail. View the log at Admin Panel > Audit Log.

Each entry includes: timestamp, user, the SQL or API call executed, row count, execution time, and success/failure status. The audit log is stored locally in the Docker volume and never transmitted externally.

Diagnostics

The diagnostics panel at Admin Panel > Diagnostics provides a one-click health check of all configured connections. Use it to verify:

• Database connectivity (SSH + Oracle for EBS/PeopleSoft)
• API connectivity (Maximo REST endpoint)
• LLM provider connectivity
• Pattern loading status

If any connection fails, the diagnostics output includes the specific error to help troubleshoot.

User Guide

This section is for everyone who uses Interpretos to ask questions — you don't need admin access for any of this.

Asking Questions

Select your integration from the dropdown at the top of the chat (e.g. Oracle EBS, Maximo, PeopleSoft), then type your question in natural language.

Tips for better results

• Be specific — "What is the status of PO 4281?" works better than "Show me POs"
• Use your normal vocabulary — The AI understands screen labels ("Total Cost") and database names ("totalcost") equally well
• Ask follow-up questions — The AI remembers your conversation context. After asking about a work order, you can say "What materials were used?" without repeating the WO number
• Try analytical questions — "Which assets cost us most in maintenance?" or "What work orders are overdue?" — the AI can aggregate, sort, and analyze data across records

Example queries by role

EBS Login (Row-Level Security)

If your admin has set up per-user credentials for Oracle EBS, you'll see an EBS Login bar at the top of the chat when Oracle EBS is selected. Enter your EBS username and password to log in. Your queries will then be filtered to only the data you're authorized to see (your operating units, ledgers, and organizations).

Click Logout to return to the default access level.

Custom Instructions (User)

You can add personal instructions that the AI will follow in all your conversations. These are your own preferences, separate from the admin-level instructions that apply to everyone.

Set them in your user settings (click your username in the top-right corner).

What to put here

• Your context — "I am the maintenance planner for the Bedford site. When I ask about work orders, I usually mean BEDFORD site only"
• Response preferences — "I prefer concise answers with tables rather than long paragraphs"
• Common shortcuts — "When I say 'my POs', I mean purchase orders where the buyer is JSMITH"
• Language preferences — "Please respond in Spanish" or "Use metric units"

Troubleshooting

Common issues and how to resolve them.

docker compose logs interpretos-local

ssh -i ~/.ssh/id_rsa root@your-ebs-server

ssh -i ~/.ssh/id_rsa oracle2@your-peoplesoft-server

docker exec interpretos-local python /app/reset-password.py

docker exec interpretos-local python /app/reset-password.py <username> <new-password>

Licensing & Updates

Free Evaluation

Interpretos Local includes a 30-day free evaluation period with full access to all integrations. No license file is needed — just install and start using it.

License Management

After your evaluation, upload a license file to continue using the product. Your license can be managed at Admin Panel > License.

License status indicators

Installing a license

You can install a license in three ways:

1. Admin Panel UI: Go to Admin Panel > License > Upload License, paste the JSON content, and click Install
2. File upload: Upload a .json file directly in the Admin Panel
3. Docker command:
   Copy

   docker cp license.json interpretos-local:/app/data/license.json

Updating

All your settings, users, credentials, and audit history are preserved across updates.

Check for updates

Go to Admin Panel > Updates and click Check Now to see if a newer version is available.

Apply an update

In the directory containing your docker-compose.yml:

docker compose pull && docker compose up -d

Docker will recreate the container with the new version. The data volume is untouched — your configuration carries over automatically.

Verify the update

Open Admin Panel > Updates to confirm the new version number, or from the command line:

curl -s http://localhost:8080/api/version

Data Persistence

All data is stored in the Docker volume (interpretos-data) and persists across container restarts and upgrades. This includes:

• Configuration and credentials (encrypted at rest)
• User accounts and per-user credentials
• Custom instructions (admin and user)
• License file
• Query audit log
• Telemetry audit log

API & Automation

Interpretos Local exposes a REST API that lets you build integrations — Slack bots, dashboards, scripts, or anything that queries your enterprise data programmatically.

Interactive API Reference (Swagger UI)

A full interactive API reference is built into every Interpretos Local instance. Open it at:

The Swagger UI lets you browse every endpoint, see request/response schemas, and try requests directly from your browser.

Authentication

Two authentication methods are supported:

• JWT Bearer Token — Log in via POST /api/auth/login with username and password. Use the returned token in the Authorization: Bearer <token> header.
• API Key — Create an API key in Admin Panel > API Keys. Pass it in the X-API-Key header or as Authorization: Bearer ik_...

API keys inherit the RBAC permissions of the user they are assigned to. An API key for an admin user can access admin-only endpoints; a key for a regular user is limited to that user's data and permissions.

Quick Start: Chat API

Send a natural-language question and get an AI-powered answer from your connected enterprise system:

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?"}'

Key Endpoints

For the complete list of 40+ endpoints with request/response schemas, see the interactive API reference in your running instance.

Bulk User Provisioning

For organizations with many users, the bulk API lets you create hundreds of users and set their integration credentials in a single request:

curl -X POST http://localhost:8080/api/admin/users/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ik_admin_key_here" \
  -d '{
    "users": [
      {"username": "jsmith", "password": "temp123!", "display_name": "John Smith",
       "credentials": {"maximo": {"API_KEY": "abc123", "API_BASE": "https://maximo.example.com/api"}}},
      {"username": "jdoe", "password": "temp456!", "display_name": "Jane Doe"}
    ],
    "update_existing": false
  }'

The operation never fails the entire batch for one invalid user — errors are collected and returned alongside successful results. Maximum 500 users per request.