Skip to main content

Let's Start

This tutorial will guide you through the initial setup required to deploy and run the Contacter platform. Over the course of this baseline implementation, you can iteratively customize, improve, and fine-tune your configurations to better align with your enterprise architecture requirements.

info Keep the Record Ingestion Workflow​

Let's capture your raw customer interaction data and ensure it is structured and securely ingested into your persistent storage databases.

1. Hardware & Environment Provisioning​

All core binaries are compiled for native execution on Linux x64 systems. If your infrastructure requires specific platform distributions, custom cross-compiled binaries can be provided upon request.

Except for the targeted hardware acceleration pipelines detailed below, the Contacter toolkit functions as a lightweight consumer of system memory and computing blocks. A minimum environment specification of 32GB RAM is highly recommended for stable operation.

You will also need to provision a local or remote relational database cluster. Storage size requirements will scale based on the total daily volume of interaction minutes and incoming multi-channel messages. Contacter natively supports PostgreSQL and soon also MySQL database engines.

The infrastructure footprint varies depending on the modules you run:

  • To execute the Transcriptor or Contacter CLI, you only require a standard host machine.
  • To execute the Ainter orchestration engine, you must establish secure access to an active LLM gateway.
  • To execute the Placer ingestion tool, you must provision a target database instance along with its corresponding routing connections.

Specialized Hardware Requirements​

Certain pipeline optimization tasks enforce specific architectural dependencies:

  • Speaker Diarization (Pyannote Pipeline)
    • Executes locally on the host machine running the Transcriber binary. Performance scales optimally on NVIDIA GPUs featuring native CUDA acceleration support. For small-scale testing layouts, the engine can fall back to standard CPU thread compute models.
  • Audio Transcription (Faster-Whisper Framework)
    • Executes locally on the host machine running the Transcriber binary. Highly optimized for parallel processing via NVIDIA CUDA GPU acceleration layers. CPU-only computation models can be deployed for low-volume testing environments.
  • Large Language Model Access (LLM Integration)
    • It is highly recommended to leverage managed external cloud API endpoints. We suggest initializing an enterprise account on OpenRouter to easily cross-test your prompt logic across multiple commercial vendor layers. There are numerous free models available to prototype and benchmark your Cequation prompts.
    • Alternatively, you can instantiate local offline models on your own servers using the Ollama orchestrator. Note that local hosting requires dedicated, high-tier hardware configurations capable of handling the computing complexity of your targeted model weights.

2. Install the Contacter Tool Set​

Contacter is supplied with two files. A tar.gz file with all binaries to be executed and an install.sh file to performe the instalation.

  1. Check the Download Document in order to download the complete Suite
  2. Register an account in our site and generate api_token to run the binaries

2. Base Configuration Setup​

Before using the utility suite, you must configure your local environment matrices. Begin by creating and initializing your base contacter.yaml and keys.yaml manifests. While the system operates on secure internal default states, you must manually populate the following mandatory integration parameters:

A. Pyannote Diarization Ingestion​

  1. Register a Hugging Face Account: If you do not possess enterprise credentials, navigate to the official Hugging Face website and sign up for a free user account.
  2. Accept Model Terms of Use: Pyannote requires explicit repository gate authentication before allowing automated layout downloads. Log in to your Hugging Face dashboard and manually accept the usage terms for both core repositories:
    • Access the pyannote/speaker-diarization-3.1 layout page (or the most current production release branch), populate the short organization identity form, and click Accept Conditions.
    • Access the pyannote/segmentation-3.0 model page and click Accept Conditions to authorize access. Note: Failure to manually accept these repository data constraints will cause the Transcriber pipeline to throw a 401 Client Error authorization failure, even if your API token is structurally correct.
  3. Generate a User Access Token: Navigate directly to your account security portal at hf.co/settings/tokens. Click on Create new token, set the token permissions scope to Read (Read-only authorization is sufficient to fetch the underlying weights), assign a descriptive name (e.g., pyannote-token), and hit generate. Copy the string key immediately (it features an hf_... prefix) and store it securely.
  4. Bind Credentials: Open your local keys.yaml file and map the token to the pyannote_hp_token configuration parameter.

B. Cryptographic Digital Signatures​

  1. Generate RSA Key Pairs: To guarantee unalterable data integrity trails across your CTT ledgers, you must sign the JSON matrices using a local corporate key pair. Generate a secure, 2048-bit AES-encrypted private key and extract its public key component via OpenSSL: 
    openssl genpkey -algorithm RSA -out private_key_protected.pem -pkeyopt rsa_keygen_bits:2048 -aes256
    # Enter and confirm your secure pass-phrase
    openssl rsa -pubout -in private_key_protected.pem -out public_key.pem
  2. Configure Signature Paths: Access your contacter.yaml file and add the absolute file path references to your generated keys under the SIGNATURE layout block.
  3. Map Pass-phrase Variable: Store your secure private key pass-phrase inside the keys.yaml file under the privatekey_password configuration key.

C. LLM Orchestration Access​

If your initial roadmap is restricted to audio transcription tasks, you can temporarily skip this step. Running the Ainter data-enrichment tool requires establishing a valid LLM gateway connection via OpenRouter or a local Ollama instance.

  1. Register an OpenRouter Account: Navigate to openrouter.ai/sign-up and authenticate using your preferred enterprise Single Sign-On (SSO) social login (Google/GitHub) or input a standard business email address and activate the verification link.
  2. Provision an API Access Key: Click on your profile dashboard in the upper-right corner, navigate to the Keys interface section, and click Create API Key. Assign a name to your application client (e.g., test-app), establish an optional cost spending ceiling for billing safety, and copy the generated secret string (sk-or-v1-...).
  3. Manage Credit Balances: OpenRouter natively supports dozens of open-weights models (such as Llama, Qwen, and Gemma variants) that require zero financial funding and can be utilized with a $0 account balance. For premium commercial models (such as GPT-4, Claude 3.5, or Gemini Pro), top up your developer credits page via Stripe or cryptocurrency. Invoicing is metered strictly per token usage.
  4. Bind Ingestion Keys: Paste your secret API key into your keys.yaml file under the openrouter_openai_api_key property.
  5. Bind Ingestion Actions: Map your endpoint criteria inside one of your ainter_*.yaml execution files. You can copy the default ainter_identify.yaml template and swap the model identifier to target your preferred weights.

D. Database & Persistence Layer​

Configuring database routing parameters is required only if you are executing ingestion routines via the Placer module.

  1. Initialize Target Relational Schemas: Create your target database infrastructure. For baseline rollouts, ensure you have structured tables ready to ingest agents, customers, interactions, phrases, and issues records.
  2. Provision Your Database Engine: Spin up a local or remote database instance running a verified PostgreSQL or MySQL deployment.
  3. Map Connection Parameters: Open your contacter.yaml configuration manifest and populate the explicit network values for your target host, port, database name, user account, and target database schema.
  4. Bind Database Security: Store the database password key inside keys.yaml under the database_password key property.
  5. Configure Semantic Search Parameters: Navigate to the EMBEDDINGS block inside your contacter.yaml file and declare the vector dimensions your columns require. If you deploy your initial configurations using the built-in local Hugging Face sentence-transformers library, you do not need to establish an external cloud OpenRouter gateway or run an active local Ollama background server.

3. Executing the Transcription Pipeline​

To test the audio processing engine, access a configured Linux host environment (a CUDA GPU environment is recommended, but CPU fallback is perfectly sufficient for benchmarking). Execute the following terminal command:

# General syntax: transcriber [filein_or_folder] [pathout] -v [verbosity_level]
transcriber linein_agentid_customerid_date.wav data/transcription -v 4

The Transcriber pipeline automatically parses primary keys (Line, Agent, Customer, Date) straight from the source filename structure. Standardizing this token layout is a critical operational workflow requirement, ensuring that every incoming .wav or .mp3 recording passing through your media storage servers automatically encapsulates session identifiers. While you can override these values manually using discrete execution arguments, filename parsing removes the overhead of changing script variables for each file during automated batch runs.

Verify if the utility successfully generated the unified CTT ledger file in your designated output path. Once verified, you can proceed to data evaluation.

4. Inspecting the CTT Dataset Ledger​

Once you have generated your first native CTT document, you can safely audit, read, and inspect its internal JSON schema arrays using the Contacter CLI utility:

# General syntax: contacter [YourCTTFile.ctt] -v [verbosity_level]
contacter data/transcription/linein_agentid_customerid_date_0.ctt -v 4

This read-only command renders the complete hierarchical dataset of the CTT file in your terminal, detailing verified speaker directories, conversational turn loops, and raw phrase blocks. The Contacter CLI can also be used to apply structural updates or manual metadata modifications to the file. For an exhaustive breakdown of command arguments, consult the Contacter core reference manual. If the output matrix is structurally valid, you are ready to proceed to the next step.

5. Augmenting Data via AI Enrichment Mappings​

Now, you can unleash the orchestration capabilities of the platform to enrich your local CTT files with deep semantic context. A typical initial production goal is to evaluate the raw phrase stream and automatically classify the specific conversational profile of each distinct speaker channel.

Ensure you have the default ainter_identify.yaml configuration template present in your working workspace directory (you can freely translate the inner prompt strings into your preferred native language if required).

First, execute the Ainter workflow command with the test flag enabled to perform prompt validation:

# General syntax: ainter [YourCTTFile.ctt] [pathout] [action_name] -t (dry-run prompt test) -v [verbosity]
ainter data/transcription/linein_agentid_customerid_date_0.ctt data/identify identify -t -v 4

This dry-run command compiles and prints the entire concatenated prompt payload directly to your terminal. Use this stage to verify that all context windows and dynamic data injections are aligned, or to make adjustments to your ainter_identify.yaml file.

Once your prompts are optimized, execute the command again without the -t or --testprompt flag to trigger the active LLM connection.

The ingestion engine will automatically generate an enriched CTT ledger in your designated target folder (data/identify). This file preserves your original data structure under an incremented tracking version, naming the new document linein_agentid_customerid_date_1.ctt. You can run the Contacter CLI utility against this file to confirm that all target speaker indices now possess structured profile classifications.

Important Note on Model Selection: To achieve stable results, you must deploy an LLM that is smart enough to handle strict instructions and robust enough to adhere to specific JSON format outputs. The Ainter parser utilizes programmatic validation layers to extract structured JSON data from the model response. If the LLM generates poorly formatted strings or drops markdown wrappers outside the schema boundaries, the execution will abort, an ingestion error will be logged, and the new CTT version file will not be written.

If your speaker identification workflow executes successfully, you can replicate this exact pipeline to extract semantic abstracts by deploying your ainter_summary.yaml rule set. This action block appends a call summary paragraph and a structured inventory of unresolved technical issues, saving the results out to linein_agentid_customerid_date_2.ctt. Once your compiled files match your quality criteria, you can proceed to the final persistence phase.

6. Relational & Vector Database Ingestion​

The final phase involves transferring your local version-controlled CTT file datasets directly into your central business database layers.

Before initializing execution, verify that your relational network credentials and host properties are fully populated inside your configuration files. Next, open your target database mapping layout (e.g., placer_format01.yaml or a custom configuration file), define your targeted destination tables, and adjust your column data type definitions to align with your system architecture.

Once your mapping configurations are verified, execute the Placer ingestion tool:

# General syntax: placer [YourCTTFile.ctt] [loader_name] -v [verbosity_level]
placer data/identify/linein_agentid_customerid_date_1.ctt callupload -v 4

The Placer application manages format serialization under the hood. It maps your conversational records, compiles execution analytics, processes text vector embedding operations, and automatically uploads the resulting arrays into your relational tables.

Log in to your target database interface client and run verification queries to confirm that all records, JSON metadata fields, and vector coordinates were ingested successfully. Once verified, your first end-to-end Contacter automation deployment pipeline is complete.

Leverage the Knowledge​

TBD