Skip to content

Operating Modes

The open-source Portiere SDK operates in local mode only. All data processing, storage, and AI inference happen on your machine. Cloud and hybrid modes are available through Portiere Cloud.

Table of Contents

Intent-Based Configuration

In the open-source SDK, effective_mode and effective_pipeline always return "local". If an api_key is provided to PortiereConfig, it is ignored and a warning is emitted.

What You Configure Inferred Mode Inferred Pipeline
Nothing (defaults) local local
knowledge_layer and/or llm local local
api_key (ignored with warning) local local 
# Fully local — configure your local AI components
config = PortiereConfig(
    knowledge_layer=KnowledgeLayerConfig(backend="bm25s", bm25s_corpus_path="./vocab.json"),
)

# api_key is ignored in the open-source SDK (warning emitted)
config = PortiereConfig(api_key="pt_sk_...")
# effective_mode -> "local", effective_pipeline -> "local"

Local Mode (Default)

Zero cloud dependency. All data stays on your machine.

When to Use

  • Data cannot leave your environment (regulatory, compliance, air-gapped networks).
  • You want full control over every component.
  • You have sufficient local compute for embedding generation and LLM inference.
  • Single-user workflow with no collaboration requirement.

Configuration

import portiere
from portiere.config import PortiereConfig, LLMConfig
from portiere.engines import PolarsEngine

# Option A: Local with Ollama for LLM
config = PortiereConfig(
    llm=LLMConfig(
        provider="ollama",
        endpoint="http://localhost:11434",
        model="llama3"
    )
)
# effective_mode="local", effective_pipeline="local"
project = portiere.init(name="Air-Gapped Migration", engine=PolarsEngine(), config=config)

# Option B: Local storage but using OpenAI directly (you manage the API key)
config = PortiereConfig(
    llm=LLMConfig(
        provider="openai",
        api_key="sk-...",
        model="gpt-4o"
    )
)
project = portiere.init(name="Local + OpenAI", engine=PolarsEngine(), config=config)

YAML

llm:
  provider: ollama
  endpoint: http://localhost:11434
  model: llama3

What Happens

  1. Project artifacts are stored under ~/.portiere/projects/<project-name>/.
  2. Embedding models (SapBERT) are downloaded to ~/.portiere/models/ on first use and cached.
  3. LLM calls go to the configured provider (Ollama, OpenAI, etc.) -- Portiere Cloud is never contacted.
  4. Knowledge layer search runs entirely in-process (BM25s or FAISS).

Storage Layout

~/.portiere/
  projects/
    Local Migration/
      project.json          # Project metadata
      sources/              # Registered source file references
      schema_mappings/      # Schema mapping artifacts
      concept_mappings/     # Concept mapping artifacts
      etl/                  # Generated ETL scripts and logs
  models/
    SapBERT-from-PubMedBERT-fulltext/   # Cached embedding model
    ms-marco-MiniLM-L-6-v2/            # Cached reranker model

Hybrid Sync: push() and pull()

In the open-source SDK, push() and pull() raise NotImplementedError. These methods require Portiere Cloud for team-based synchronization and multi-reviewer collaboration.

project.push()   # raises NotImplementedError
project.pull()   # raises NotImplementedError

Single-user review is available locally (v0.3.1+): pip install "portiere-health[review]" then portiere review <project-dir> launches a Streamlit-based Mapping Review UI at http://127.0.0.1:8501. See docs/mapping-review-ui.md. For multi-user team collaboration with auth, visit Portiere Cloud.

Decision Matrix

Requirement Configuration
Air-gapped or regulated environment knowledge_layer + llm (no api_key)
Single user, full local control knowledge_layer + llm
PHI/PII data, even column names are sensitive llm=LLMConfig(provider="ollama")
CI/CD pipeline, automated mapping in Docker knowledge_layer + llm
Single-user local mapping review (v0.3.1+) pip install "portiere-health[review]" → portiere review <project-dir>
Team collaboration with multi-reviewer auth Use Portiere Cloud

See Also