Quickstart

This guide walks through the Python API: turning a raw text sample into a TextFSM template, then compiling that template into its AST, canonical TextFSM, readable DSL, and recognizer patterns.

Prerequisites

You need an API key for at least one supported provider, set as an environment variable:

Provider	provider value	Environment variable
OpenAI	"openai"	OPENAI_API_KEY
Anthropic	"anthropic"	ANTHROPIC_API_KEY
Gemini	"gemini"	GEMINI_API_KEY
DeepSeek	"deepseek"	DEEPSEEK_API_KEY
Groq	"groq"	GROQ_API_KEY
xAI (Grok)	"xai"	XAI_API_KEY
Together AI	"together"	TOGETHER_API_KEY
Fireworks AI	"fireworks"	FIREWORKS_API_KEY
Cerebras	"cerebras"	CEREBRAS_API_KEY
Perplexity	"perplexity"	PERPLEXITY_API_KEY
OpenRouter	"openrouter"	OPENROUTER_API_KEY
Moonshot AI (Kimi)	"moonshot"	MOONSHOT_API_KEY
Mistral AI	"mistral"	MISTRAL_API_KEY
Amazon Bedrock	"bedrock"	BEDROCK_REGION (or BEDROCK_DEFAULT_REGION) + AWS credential chain
Cohere	"cohere"	COHERE_API_KEY
Google Vertex AI	"vertexai"	VERTEXAI_PROJECT + VERTEXAI_REGION + GCP ADC credential chain
Oracle OCI	"oci"	OCI_COMPARTMENT_ID + ~/.oci/config credential file (OCI_REGION optional)
Azure OpenAI	"azure"	AZURE_API_KEY, AZURE_ENDPOINT, AZURE_API_VERSION

pip install textfsm-ai
export OPENAI_API_KEY=sk-...

1. Ask an LLM to generate a template

import os
import textfsm_ai

sample = """\
interface GigabitEthernet0/1
 description Uplink to core switch
interface GigabitEthernet0/2
 description Downlink to access switch
"""

result = textfsm_ai.generate(
    sample,
    provider="openai",
    api_key=os.environ["OPENAI_API_KEY"],
    model="gpt-4o-mini",
)

if result.ready:
    print(result.template)     # the generated TextFSM template
    print(result.records)      # parsed records the LLM extracted
    print(result.variables)    # {"iface": "explanation of this variable", ...}
    print(result.handling)     # notes on how ambiguous lines were handled
else:
    print("Generation failed:", result.reason)

generate() never raises for an ordinary LLM/generation failure (rate limits, retry exhaustion, an unparsable response) — check result.ready and read result.reason instead of wrapping the call in try/except.

If you only need one piece of the result, use the matching shortcut instead of pulling the whole object apart yourself:

template = textfsm_ai.to_llm_template(sample, provider="openai", api_key=..., model="gpt-4o-mini")
records = textfsm_ai.to_llm_records(sample, provider="openai", api_key=..., model="gpt-4o-mini")

Note: to_llm_template() returns the failure reason (a string) instead of an empty string if generation didn't succeed — it's a shortcut for the .template field, not a separate cheaper call, so check to_llm_result() first if you need to tell "failed" apart from "genuinely returned this string."

2. Compile a template into its AST, canonical form, and recognizers

Once you have a template (from generate(), or one you wrote by hand), compile it to get the parsed AST, the canonical (regex-expanded) TextFSM template, a human-readable DSL form, and recognizer patterns:

dsl = textfsm_ai.compile_dsl(result.template, result.records)

if dsl.ready:
    print(dsl.canonical)     # canonical TextFSM template
    print(dsl.readable)      # human-readable DSL
    print(dsl.recognizers)   # regex patterns that detect this block of text
    print(dsl.ast)           # the parsed TemplateAST
else:
    print("Compile failed:", dsl.reason)

Same shortcut pattern applies here: to_canonical(), to_readable(), to_recognizers(), and to_ast() each take the same (template, records) parameters as compile_dsl().

3. Or run the whole pipeline in one call

run_pipeline() does both steps above end-to-end and packages the result for you, in one of four verbosity modes:

output = textfsm_ai.run_pipeline(
    sample,
    provider="openai",
    api_key=os.environ["OPENAI_API_KEY"],
    model="gpt-4o-mini",
    mode="debug",  # "quiet" | "default" | "info" | "debug"
)

print(output.output)   # formatted text for the chosen mode
print(output.passed)   # True/False

Using an Azure deployment

Azure uses a deployment name in place of model, plus endpoint and api_version:

result = textfsm_ai.generate(
    sample,
    provider="azure",
    api_key=os.environ["AZURE_API_KEY"],
    model=os.environ["AZURE_DEPLOYMENT"],  # deployment name
    endpoint=os.environ["AZURE_ENDPOINT"],
    api_version=os.environ["AZURE_API_VERSION"],
)

Using Amazon Bedrock

Bedrock takes no api_key at all — pass region instead, and AWS credentials are resolved automatically via boto3's own credential chain (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN, ~/.aws/credentials, or an IAM role):

result = textfsm_ai.generate(
    sample,
    provider="bedrock",
    api_key="",
    model="anthropic.claude-haiku-4-5-v1:0",
    region=os.environ["BEDROCK_REGION"],
)

run_pipeline() accepts the same region keyword.

Using Google Vertex AI

Vertex AI also takes no api_key — pass project and region (GCP "location") instead, and credentials are resolved automatically via Google Cloud's Application Default Credentials (a service account key file via GOOGLE_APPLICATION_CREDENTIALS, gcloud auth application-default login, or workload identity):

result = textfsm_ai.generate(
    sample,
    provider="vertexai",
    api_key="",
    model="gemini-2.5-flash",
    project=os.environ["VERTEXAI_PROJECT"],
    region=os.environ["VERTEXAI_REGION"],
)

run_pipeline() accepts the same project/region keywords. Vertex AI serves the same Gemini models as the native "gemini" provider under identical model IDs, so it must always be selected explicitly via provider="vertexai" — there's no automatic way to tell "call this model via Vertex" apart from "call it via the Gemini Developer API" from the model name alone.

Using Oracle OCI

OCI also takes no api_key — pass compartment_id instead (an OCID identifying which OCI compartment to bill and scope the request to), and credentials are resolved automatically from ~/.oci/config (the DEFAULT profile, same file the OCI CLI itself uses). region is optional here: if omitted, whatever region is already set in ~/.oci/config is used.

result = textfsm_ai.generate(
    sample,
    provider="oci",
    api_key="",
    model="meta.llama-3.3-70b-instruct",
    compartment_id=os.environ["OCI_COMPARTMENT_ID"],
    region=os.environ.get("OCI_REGION"),
)

run_pipeline() accepts the same compartment_id/region keywords. OCI's "vendor.model-name" model IDs (meta.llama-3.3-70b-instruct, xai.grok-4-fast-reasoning) share vendor prefixes with Amazon Bedrock's own re-hosted namespace, so OCI must always be selected explicitly via provider="oci". Only Meta Llama and xAI Grok models are supported — Cohere models on OCI use a different, incompatible request/response shape and are reachable through this package's native "cohere" or "bedrock" providers instead.

Next steps

• See Providers for the full list of supported providers, their credentials, and any provider-specific quirks.
• See the API Reference for every function and result type.
• See the CLI Guide for the equivalent textfsm-ai command-line workflow.