PythonPrimary SDKFull feature parity

Python SDK

The reference implementation of TrueNorth. All features land in Python first. Supports Python 3.9+.

PyPI package name
Install truenorth-framework — not truenorth (that's a different package on PyPI).

Installation

bash
pip install truenorth-framework

Initialize

Create an engine with your LLM provider:

python/main.py
from truenorth import TrueNorthEngine
engine = TrueNorthEngine(
    provider="openai",          # "openai" | "anthropic" | "gemini" | "ollama"
    model="gpt-4o-mini",
    api_key="sk-...",           # omit for ollama
    compliance=["dpdp", "gdpr"] # optional compliance modules
)

Create a Session

python/session.py
# From a YAML file
session = engine.create_session(
    yaml_path="agents/medical_intake.yaml",
    session_id="session_abc123",       # optional — auto-generated if omitted
    metadata={"channel": "whatsapp"}   # optional
)
# Or from an inline dict
session = engine.create_session(
    schema={
        "id": "quick_demo",
        "fields": [
            {"name": "name", "type": "text", "required": True},
            {"name": "age",  "type": "integer", "range": [0, 120]},
        ]
    }
)

Send a Message

python/chat.py
response = await session.send("Hi, I'm Priya and I'm 28")
print(response.message)      # "Thanks Priya! What is your primary goal?"
print(response.extracted)    # {"name": "Priya", "age": 28}
print(response.pending)      # ["goal", "height", "weight"]
print(response.cost_usd)     # 0.000043
print(response.stage)        # "field_extraction"
print(response.complete)     # False

Get Structured Output

python/output.py
# After session.complete is True
output = session.get_output()
print(output.json())
# {
#   "patient_name": "Priya",
#   "age": 28,
#   "chief_complaint": "chest pain",
#   ...
# }
print(output.fields["age"].confidence)   # 0.97
print(output.fields["age"].source_turn)  # 3
print(output.total_cost_usd)             # 0.0043
print(output.turns)                      # 9

API Reference

MethodParametersReturns
TrueNorthEngine()provider, model, api_key, compliance?Engine
engine.create_session()yaml_path | schema, session_id?, metadata?Session
await session.send()message: strTurnResponse
session.get_output()—SessionOutput
session.reset()—None
session.export_json()path?: strdict | None
engine.load_template()name: str, version?: strYAMLSchema