parseforge 0.2.10__tar.gz → 0.3.0__tar.gz

{parseforge-0.2.10/parseforge.egg-info → parseforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parseforge
-Version: 0.2.10
+Version: 0.3.0
 Summary: LLM-driven pipeline that forges, validates, and promotes TextFSM templates from network CLI output
 Author-email: Tuyen Mathew Duong <tuyen@geekstrident.com>
 Maintainer-email: Tuyen Mathew Duong <tuyen@geekstrident.com>
@@ -26,52 +26,61 @@ License-File: LICENSE
 Requires-Dist: click>=8.1
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: textfsm>=1.1.0
-Requires-Dist: textfsm-ai>=0.6.1
+Requires-Dist: textfsm-ai>=0.7.1
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
-Requires-Dist: textfsm-ai[anthropic]>=0.6.1; extra == "anthropic"
+Requires-Dist: textfsm-ai[anthropic]>=0.7.1; extra == "anthropic"
 Provides-Extra: deepseek
 Requires-Dist: openai>=1.0.0; extra == "deepseek"
-Requires-Dist: textfsm-ai[deepseek]>=0.6.1; extra == "deepseek"
+Requires-Dist: textfsm-ai[deepseek]>=0.7.1; extra == "deepseek"
 Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
-Requires-Dist: textfsm-ai[openai]>=0.6.1; extra == "openai"
+Requires-Dist: textfsm-ai[openai]>=0.7.1; extra == "openai"
 Provides-Extra: groq
 Requires-Dist: openai>=1.0.0; extra == "groq"
-Requires-Dist: textfsm-ai[groq]>=0.6.1; extra == "groq"
+Requires-Dist: textfsm-ai[groq]>=0.7.1; extra == "groq"
 Provides-Extra: xai
 Requires-Dist: openai>=1.0.0; extra == "xai"
-Requires-Dist: textfsm-ai[xai]>=0.6.1; extra == "xai"
+Requires-Dist: textfsm-ai[xai]>=0.7.1; extra == "xai"
 Provides-Extra: together
 Requires-Dist: openai>=1.0.0; extra == "together"
-Requires-Dist: textfsm-ai[together]>=0.6.1; extra == "together"
+Requires-Dist: textfsm-ai[together]>=0.7.1; extra == "together"
 Provides-Extra: fireworks
 Requires-Dist: openai>=1.0.0; extra == "fireworks"
-Requires-Dist: textfsm-ai[fireworks]>=0.6.1; extra == "fireworks"
+Requires-Dist: textfsm-ai[fireworks]>=0.7.1; extra == "fireworks"
 Provides-Extra: perplexity
 Requires-Dist: openai>=1.0.0; extra == "perplexity"
-Requires-Dist: textfsm-ai[perplexity]>=0.6.1; extra == "perplexity"
+Requires-Dist: textfsm-ai[perplexity]>=0.7.1; extra == "perplexity"
 Provides-Extra: openrouter
 Requires-Dist: openai>=1.0.0; extra == "openrouter"
-Requires-Dist: textfsm-ai[openrouter]>=0.6.1; extra == "openrouter"
+Requires-Dist: textfsm-ai[openrouter]>=0.7.1; extra == "openrouter"
 Provides-Extra: moonshot
 Requires-Dist: openai>=1.0.0; extra == "moonshot"
-Requires-Dist: textfsm-ai[moonshot]>=0.6.1; extra == "moonshot"
+Requires-Dist: textfsm-ai[moonshot]>=0.7.1; extra == "moonshot"
 Provides-Extra: cerebras
 Requires-Dist: openai>=1.0.0; extra == "cerebras"
-Requires-Dist: textfsm-ai[cerebras]>=0.6.1; extra == "cerebras"
+Requires-Dist: textfsm-ai[cerebras]>=0.7.1; extra == "cerebras"
 Provides-Extra: mistral
 Requires-Dist: mistralai==1.10.0; extra == "mistral"
-Requires-Dist: textfsm-ai[mistral]>=0.6.1; extra == "mistral"
+Requires-Dist: textfsm-ai[mistral]>=0.7.1; extra == "mistral"
 Provides-Extra: cohere
 Requires-Dist: cohere==5.21.1; extra == "cohere"
-Requires-Dist: textfsm-ai[cohere]>=0.6.1; extra == "cohere"
+Requires-Dist: textfsm-ai[cohere]>=0.7.1; extra == "cohere"
 Provides-Extra: azure
 Requires-Dist: azure-ai-inference>=1.0.0b9; extra == "azure"
-Requires-Dist: textfsm-ai[azure]>=0.6.1; extra == "azure"
+Requires-Dist: textfsm-ai[azure]>=0.7.1; extra == "azure"
 Provides-Extra: gemini
 Requires-Dist: google-genai>=0.2.0; extra == "gemini"
-Requires-Dist: textfsm-ai[gemini]>=0.6.1; extra == "gemini"
+Requires-Dist: textfsm-ai[gemini]>=0.7.1; extra == "gemini"
+Provides-Extra: vertexai
+Requires-Dist: google-genai>=0.2.0; extra == "vertexai"
+Requires-Dist: textfsm-ai[vertexai]>=0.7.1; extra == "vertexai"
+Provides-Extra: bedrock
+Requires-Dist: boto3==1.42.97; extra == "bedrock"
+Requires-Dist: textfsm-ai[bedrock]>=0.7.1; extra == "bedrock"
+Provides-Extra: oci
+Requires-Dist: oci==2.182.0; extra == "oci"
+Requires-Dist: textfsm-ai[oci]>=0.7.1; extra == "oci"
 Provides-Extra: sampling
 Requires-Dist: netmiko>=4.0; extra == "sampling"
 Provides-Extra: dev
@@ -86,6 +95,8 @@ Requires-Dist: mistralai==1.10.0; extra == "dev"
 Requires-Dist: cohere==5.21.1; extra == "dev"
 Requires-Dist: azure-ai-inference>=1.0.0b9; extra == "dev"
 Requires-Dist: google-genai>=0.2.0; extra == "dev"
+Requires-Dist: boto3==1.42.97; extra == "dev"
+Requires-Dist: oci==2.182.0; extra == "dev"
 Provides-Extra: release
 Requires-Dist: bump2version; extra == "release"
 Requires-Dist: build; extra == "release"
@@ -128,11 +139,12 @@ command that's pure local processing (`canonical`/`readable`/`recognizers`,
 LLM (`name`, `check --provider`, `run`, `generate-template`, `trial`) needs the
 extra for whichever provider it uses: `anthropic`, `openai`, `deepseek`,
 `groq`, `xai`, `together`, `fireworks`, `perplexity`, `openrouter`,
-`moonshot`, `cerebras`, `mistral`, `cohere`, `azure`, or `gemini`.
-`--provider` defaults to `anthropic` wherever it isn't required, so that's
-the one most setups need. `pip install parseforge[sampling]` adds Netmiko
-for live device sampling; combine extras as needed, e.g.
-`pip install parseforge[anthropic,openai,deepseek,groq,xai,together,fireworks,perplexity,openrouter,moonshot,cerebras,mistral,cohere,azure,gemini,sampling]`.
+`moonshot`, `cerebras`, `mistral`, `cohere`, `azure`, `gemini`, `vertexai`,
+`bedrock`, or `oci`. `--provider` defaults to `anthropic` wherever it isn't
+required, so that's the one most setups need. `pip install
+parseforge[sampling]` adds Netmiko for live device sampling; combine
+extras as needed, e.g.
+`pip install parseforge[anthropic,openai,deepseek,groq,xai,together,fireworks,perplexity,openrouter,moonshot,cerebras,mistral,cohere,azure,gemini,vertexai,bedrock,oci,sampling]`.
 
 ## Development
 
@@ -141,12 +153,26 @@ pip install -e ".[dev,sampling]"
 pytest
 ```
 `dev` already includes the `anthropic`, `openai`, `mistralai`, `cohere`,
-`azure-ai-inference`, and `google-genai` SDKs (tests exercise all fifteen
-providers — `anthropic`, `openai`, `deepseek`, `groq`, `xai`, `together`,
-`fireworks`, `perplexity`, `openrouter`, `moonshot`, `cerebras` share just
-the first two packages, and `mistral`/`cohere`/`azure`/`gemini` each need
-their own SDK — and never silently skip) — add the specific `,<provider>`
-extra explicitly only if installing outside of `dev`.
+`azure-ai-inference`, `google-genai`, `boto3`, and `oci` SDKs (tests exercise
+all eighteen providers — `anthropic`, `openai`, `deepseek`, `groq`, `xai`,
+`together`, `fireworks`, `perplexity`, `openrouter`, `moonshot`, `cerebras`
+share just the first two packages, `mistral`/`cohere`/`azure`/`bedrock`/`oci`
+each need their own SDK, and `gemini`/`vertexai` share `google-genai` — and
+never silently skip) — add the specific `,<provider>` extra explicitly only
+if installing outside of `dev`.
+
+For tooling that expects plain `requirements.txt` files instead of pip
+extras (Docker layers, offline pins, etc), `requirements/` has one
+`requirements-<provider>.txt` per provider whose SDK isn't already
+pinned by a shared package (`anthropic`/`openai`/`azure`/`bedrock`/`oci`/
+`cohere`/`mistral`/`gemini`/`vertexai`) — each mirrors the matching
+`pyproject.toml` extra exactly (`-e .` plus that provider's SDK pin), so
+`pip install -r requirements/requirements-oci.txt` is equivalent to
+`pip install -e ".[oci]"`. To also run that provider's tests, use the
+matching `dev-<provider>.txt` instead — it layers `pytest`/`pytest-cov`
+on top via `-r requirements-<provider>.txt`, so cloning the repo and
+running `pip install -r requirements/dev-oci.txt` is enough on its own,
+no separate install step needed.
 
 Linting/formatting/type-checking/docs run through tox instead of extras — see
 `tox.ini` (`tox -e lint`/`format`/`typecheck`/`docs`), each installing its own
@@ -171,11 +197,23 @@ and `--api-key` falls back to that provider's own env var (`ANTHROPIC_API_KEY`/
 `OPENAI_API_KEY`/`DEEPSEEK_API_KEY`/etc.). A cache hit (a command already seen
 before) never touches the LLM, so no key is needed at all in that case.
 
-`--provider azure` is the one exception to the usual `--api-key`/`--model` shape —
-Azure has no fixed base_url or model catalog, so it also needs `--endpoint`
+`--provider azure`/`--provider vertexai`/`--provider bedrock`/`--provider oci`
+are the four exceptions to the usual `--api-key`/`--model` shape. Azure has
+no fixed base_url or model catalog, so it also needs `--endpoint`
 (`AZURE_ENDPOINT`), `--api-version` (`AZURE_API_VERSION`), and `--deployment`
-(`AZURE_DEPLOYMENT`, replacing `--model`). Same three options exist on
-`check --provider`, `run`, and `generate-template` below.
+(`AZURE_DEPLOYMENT`, replacing `--model`). Vertex AI has no API key at all —
+it authenticates via GCP's own Application Default Credentials — so
+`--api-key`/`AZURE_API_KEY`-style env vars don't apply; it needs
+`--gcp-project` (`VERTEXAI_PROJECT`) and `--gcp-location` (`VERTEXAI_REGION`)
+instead. Bedrock likewise has no API key at all — it authenticates via AWS's
+own credential chain — and just needs `--region` (`BEDROCK_REGION`, then
+`BEDROCK_DEFAULT_REGION`). OCI also has no API key at all — it signs each
+request cryptographically against local credentials in `~/.oci/config`
+(DEFAULT profile) — and needs both `--region` (`OCI_REGION`, then whatever
+region is already set in `~/.oci/config`) and `--compartment-id`
+(`OCI_COMPARTMENT_ID`, the OCID of the compartment/tenancy to bill and scope
+requests to). Same options exist on `check --provider`, `run`, and
+`generate-template` below.
 
 **`check`** — validate a connector or provider before spending time/tokens on a real
 run. With neither `--env` nor explicit connection flags, prints what a connector needs
@@ -216,14 +254,21 @@ parseforge run --vendor cisco --family catalyst9200 --os ios-xe --version 17.9.1
   --model claude-haiku-4-5-20251001 \
   show clock
 ```
-`--provider`/`--api-key`/`--model` are for generation. Naming has its own separate
+`--provider`/`--api-key`/`--model` are for generation (`--api-key` isn't
+required for `--provider vertexai`/`--provider bedrock`/`--provider oci`).
+Naming has its own separate
 `--naming-provider`/`--naming-api-key`/`--naming-model`, defaulting independently
 (`--naming-provider` defaults to `anthropic`; the other two fall back to that
 provider's own env var/default model) — set them explicitly if naming needs a
 different provider than generation. `--provider azure`/`--naming-provider azure`
 each get their own `--endpoint`/`--api-version`/`--deployment` (generation) and
-`--naming-endpoint`/`--naming-api-version`/`--naming-deployment` (naming) — see
-the `name` section above for what they're for.
+`--naming-endpoint`/`--naming-api-version`/`--naming-deployment` (naming);
+`--provider vertexai`/`--naming-provider vertexai` similarly get
+`--gcp-project`/`--gcp-location` and `--naming-gcp-project`/
+`--naming-gcp-location`; `--provider bedrock`/`--naming-provider bedrock` get
+`--region` and `--naming-region`; `--provider oci`/`--naming-provider oci` get
+`--region`/`--compartment-id` and `--naming-region`/`--naming-compartment-id`
+— see the `name` section above for what they're for.
 
 **`init-trial-config`** — write a placeholder `trial.yaml` to fill in, instead of
 writing one by hand:
@@ -257,8 +302,15 @@ workers: 1
 `provider`/`api_key`/`model` are one shared LLM source used for both naming and
 generation. Use the `run` command's separate `--naming-*`/`--generation-*` flags
 instead if a trial actually needs two different providers. For `provider: azure`,
-also set `endpoint`/`api_version`/`deployment` (`deployment` replaces `model`) —
-see `parseforge init-trial-config`'s generated placeholder for the exact keys.
+also set `endpoint`/`api_version`/`deployment` (`deployment` replaces `model`).
+For `provider: vertexai`, set `project`/`location` instead — `api_key` can be
+omitted entirely (Vertex AI authenticates via GCP's own Application Default
+Credentials). For `provider: bedrock`, set `region` instead — `api_key` can
+likewise be omitted entirely (Bedrock authenticates via AWS's own credential
+chain). For `provider: oci`, set `region`/`compartment_id` instead —
+`api_key` can likewise be omitted entirely (OCI authenticates via local
+request-signing credentials in `~/.oci/config`). See
+`parseforge init-trial-config`'s generated placeholder for the exact keys.
 
 **`integration`** — rebuild `integration/` for every case under `trials/` (SPEC §5
 step 8):
@@ -294,6 +346,38 @@ evaluating any gate — so running `promotion` alone after a `trial` run is enou
 pick up new evidence; a separate `integration` run is only useful if you want to
 inspect `reference-summary.json` without also promoting.
 
+## Python API
+
+Everything the CLI does is also a plain Python call — `parseforge/api.py` is the
+single supported place to import from (also re-exported at the package root):
+
+```python
+from parseforge import CliContext, LLMProviderConfig, run_command_pipeline
+from parseforge.naming import AnthropicRegexBuilder
+from parseforge.sampling.backends import NetmikoSampler
+from parseforge.sampling import DeviceConnection
+
+result = run_command_pipeline(
+    "show clock",
+    CliContext(vendor="cisco", family="catalyst9200", os="ios-xe", version="17.9.1"),
+    DeviceConnection(host="10.0.0.1", username="admin", password="secret", device_type="cisco_ios"),
+    AnthropicRegexBuilder(api_key="sk-..."),
+    NetmikoSampler(),
+    LLMProviderConfig(provider="anthropic", api_key="sk-...", model="claude-haiku-4-5-20251001"),
+)
+print(result.cli_name, result.passed, result.total_usage)
+```
+
+One function per pipeline stage (SPEC.md §5): `cli_name`/`resolve_cli_name` (naming),
+`sample` (sampling), `generate` (generation), `parse` (self-validation),
+`run_command_pipeline` (steps 1-7 in one call), `build_integration`/
+`write_reference_summary` (integration), `promote_auto`/`promote_user_reviewed`
+(promotion), `check_drift` (drift monitoring) — plus the dataclasses/enums each one
+returns or accepts. Provider-specific naming builders (`AnthropicRegexBuilder`,
+`OCIRegexBuilder`, ...) aren't re-exported at the root — import them from
+`parseforge.naming` directly. Anything not in `parseforge.api.__all__` is internal
+and may change without notice.
+
 ## Reference
 
 - [Documentation site](https://geeks-trident-llc.github.io/parseforge/) ([source](./docs/index.md))

{parseforge-0.2.10 → parseforge-0.3.0}/README.md

@@ -35,11 +35,12 @@ command that's pure local processing (`canonical`/`readable`/`recognizers`,
 LLM (`name`, `check --provider`, `run`, `generate-template`, `trial`) needs the
 extra for whichever provider it uses: `anthropic`, `openai`, `deepseek`,
 `groq`, `xai`, `together`, `fireworks`, `perplexity`, `openrouter`,
-`moonshot`, `cerebras`, `mistral`, `cohere`, `azure`, or `gemini`.
-`--provider` defaults to `anthropic` wherever it isn't required, so that's
-the one most setups need. `pip install parseforge[sampling]` adds Netmiko
-for live device sampling; combine extras as needed, e.g.
-`pip install parseforge[anthropic,openai,deepseek,groq,xai,together,fireworks,perplexity,openrouter,moonshot,cerebras,mistral,cohere,azure,gemini,sampling]`.
+`moonshot`, `cerebras`, `mistral`, `cohere`, `azure`, `gemini`, `vertexai`,
+`bedrock`, or `oci`. `--provider` defaults to `anthropic` wherever it isn't
+required, so that's the one most setups need. `pip install
+parseforge[sampling]` adds Netmiko for live device sampling; combine
+extras as needed, e.g.
+`pip install parseforge[anthropic,openai,deepseek,groq,xai,together,fireworks,perplexity,openrouter,moonshot,cerebras,mistral,cohere,azure,gemini,vertexai,bedrock,oci,sampling]`.
 
 ## Development
 
@@ -48,12 +49,26 @@ pip install -e ".[dev,sampling]"
 pytest
 ```
 `dev` already includes the `anthropic`, `openai`, `mistralai`, `cohere`,
-`azure-ai-inference`, and `google-genai` SDKs (tests exercise all fifteen
-providers — `anthropic`, `openai`, `deepseek`, `groq`, `xai`, `together`,
-`fireworks`, `perplexity`, `openrouter`, `moonshot`, `cerebras` share just
-the first two packages, and `mistral`/`cohere`/`azure`/`gemini` each need
-their own SDK — and never silently skip) — add the specific `,<provider>`
-extra explicitly only if installing outside of `dev`.
+`azure-ai-inference`, `google-genai`, `boto3`, and `oci` SDKs (tests exercise
+all eighteen providers — `anthropic`, `openai`, `deepseek`, `groq`, `xai`,
+`together`, `fireworks`, `perplexity`, `openrouter`, `moonshot`, `cerebras`
+share just the first two packages, `mistral`/`cohere`/`azure`/`bedrock`/`oci`
+each need their own SDK, and `gemini`/`vertexai` share `google-genai` — and
+never silently skip) — add the specific `,<provider>` extra explicitly only
+if installing outside of `dev`.
+
+For tooling that expects plain `requirements.txt` files instead of pip
+extras (Docker layers, offline pins, etc), `requirements/` has one
+`requirements-<provider>.txt` per provider whose SDK isn't already
+pinned by a shared package (`anthropic`/`openai`/`azure`/`bedrock`/`oci`/
+`cohere`/`mistral`/`gemini`/`vertexai`) — each mirrors the matching
+`pyproject.toml` extra exactly (`-e .` plus that provider's SDK pin), so
+`pip install -r requirements/requirements-oci.txt` is equivalent to
+`pip install -e ".[oci]"`. To also run that provider's tests, use the
+matching `dev-<provider>.txt` instead — it layers `pytest`/`pytest-cov`
+on top via `-r requirements-<provider>.txt`, so cloning the repo and
+running `pip install -r requirements/dev-oci.txt` is enough on its own,
+no separate install step needed.
 
 Linting/formatting/type-checking/docs run through tox instead of extras — see
 `tox.ini` (`tox -e lint`/`format`/`typecheck`/`docs`), each installing its own
@@ -78,11 +93,23 @@ and `--api-key` falls back to that provider's own env var (`ANTHROPIC_API_KEY`/
 `OPENAI_API_KEY`/`DEEPSEEK_API_KEY`/etc.). A cache hit (a command already seen
 before) never touches the LLM, so no key is needed at all in that case.
 
-`--provider azure` is the one exception to the usual `--api-key`/`--model` shape —
-Azure has no fixed base_url or model catalog, so it also needs `--endpoint`
+`--provider azure`/`--provider vertexai`/`--provider bedrock`/`--provider oci`
+are the four exceptions to the usual `--api-key`/`--model` shape. Azure has
+no fixed base_url or model catalog, so it also needs `--endpoint`
 (`AZURE_ENDPOINT`), `--api-version` (`AZURE_API_VERSION`), and `--deployment`
-(`AZURE_DEPLOYMENT`, replacing `--model`). Same three options exist on
-`check --provider`, `run`, and `generate-template` below.
+(`AZURE_DEPLOYMENT`, replacing `--model`). Vertex AI has no API key at all —
+it authenticates via GCP's own Application Default Credentials — so
+`--api-key`/`AZURE_API_KEY`-style env vars don't apply; it needs
+`--gcp-project` (`VERTEXAI_PROJECT`) and `--gcp-location` (`VERTEXAI_REGION`)
+instead. Bedrock likewise has no API key at all — it authenticates via AWS's
+own credential chain — and just needs `--region` (`BEDROCK_REGION`, then
+`BEDROCK_DEFAULT_REGION`). OCI also has no API key at all — it signs each
+request cryptographically against local credentials in `~/.oci/config`
+(DEFAULT profile) — and needs both `--region` (`OCI_REGION`, then whatever
+region is already set in `~/.oci/config`) and `--compartment-id`
+(`OCI_COMPARTMENT_ID`, the OCID of the compartment/tenancy to bill and scope
+requests to). Same options exist on `check --provider`, `run`, and
+`generate-template` below.
 
 **`check`** — validate a connector or provider before spending time/tokens on a real
 run. With neither `--env` nor explicit connection flags, prints what a connector needs
@@ -123,14 +150,21 @@ parseforge run --vendor cisco --family catalyst9200 --os ios-xe --version 17.9.1
   --model claude-haiku-4-5-20251001 \
   show clock
 ```
-`--provider`/`--api-key`/`--model` are for generation. Naming has its own separate
+`--provider`/`--api-key`/`--model` are for generation (`--api-key` isn't
+required for `--provider vertexai`/`--provider bedrock`/`--provider oci`).
+Naming has its own separate
 `--naming-provider`/`--naming-api-key`/`--naming-model`, defaulting independently
 (`--naming-provider` defaults to `anthropic`; the other two fall back to that
 provider's own env var/default model) — set them explicitly if naming needs a
 different provider than generation. `--provider azure`/`--naming-provider azure`
 each get their own `--endpoint`/`--api-version`/`--deployment` (generation) and
-`--naming-endpoint`/`--naming-api-version`/`--naming-deployment` (naming) — see
-the `name` section above for what they're for.
+`--naming-endpoint`/`--naming-api-version`/`--naming-deployment` (naming);
+`--provider vertexai`/`--naming-provider vertexai` similarly get
+`--gcp-project`/`--gcp-location` and `--naming-gcp-project`/
+`--naming-gcp-location`; `--provider bedrock`/`--naming-provider bedrock` get
+`--region` and `--naming-region`; `--provider oci`/`--naming-provider oci` get
+`--region`/`--compartment-id` and `--naming-region`/`--naming-compartment-id`
+— see the `name` section above for what they're for.
 
 **`init-trial-config`** — write a placeholder `trial.yaml` to fill in, instead of
 writing one by hand:
@@ -164,8 +198,15 @@ workers: 1
 `provider`/`api_key`/`model` are one shared LLM source used for both naming and
 generation. Use the `run` command's separate `--naming-*`/`--generation-*` flags
 instead if a trial actually needs two different providers. For `provider: azure`,
-also set `endpoint`/`api_version`/`deployment` (`deployment` replaces `model`) —
-see `parseforge init-trial-config`'s generated placeholder for the exact keys.
+also set `endpoint`/`api_version`/`deployment` (`deployment` replaces `model`).
+For `provider: vertexai`, set `project`/`location` instead — `api_key` can be
+omitted entirely (Vertex AI authenticates via GCP's own Application Default
+Credentials). For `provider: bedrock`, set `region` instead — `api_key` can
+likewise be omitted entirely (Bedrock authenticates via AWS's own credential
+chain). For `provider: oci`, set `region`/`compartment_id` instead —
+`api_key` can likewise be omitted entirely (OCI authenticates via local
+request-signing credentials in `~/.oci/config`). See
+`parseforge init-trial-config`'s generated placeholder for the exact keys.
 
 **`integration`** — rebuild `integration/` for every case under `trials/` (SPEC §5
 step 8):
@@ -201,6 +242,38 @@ evaluating any gate — so running `promotion` alone after a `trial` run is enou
 pick up new evidence; a separate `integration` run is only useful if you want to
 inspect `reference-summary.json` without also promoting.
 
+## Python API
+
+Everything the CLI does is also a plain Python call — `parseforge/api.py` is the
+single supported place to import from (also re-exported at the package root):
+
+```python
+from parseforge import CliContext, LLMProviderConfig, run_command_pipeline
+from parseforge.naming import AnthropicRegexBuilder
+from parseforge.sampling.backends import NetmikoSampler
+from parseforge.sampling import DeviceConnection
+
+result = run_command_pipeline(
+    "show clock",
+    CliContext(vendor="cisco", family="catalyst9200", os="ios-xe", version="17.9.1"),
+    DeviceConnection(host="10.0.0.1", username="admin", password="secret", device_type="cisco_ios"),
+    AnthropicRegexBuilder(api_key="sk-..."),
+    NetmikoSampler(),
+    LLMProviderConfig(provider="anthropic", api_key="sk-...", model="claude-haiku-4-5-20251001"),
+)
+print(result.cli_name, result.passed, result.total_usage)
+```
+
+One function per pipeline stage (SPEC.md §5): `cli_name`/`resolve_cli_name` (naming),
+`sample` (sampling), `generate` (generation), `parse` (self-validation),
+`run_command_pipeline` (steps 1-7 in one call), `build_integration`/
+`write_reference_summary` (integration), `promote_auto`/`promote_user_reviewed`
+(promotion), `check_drift` (drift monitoring) — plus the dataclasses/enums each one
+returns or accepts. Provider-specific naming builders (`AnthropicRegexBuilder`,
+`OCIRegexBuilder`, ...) aren't re-exported at the root — import them from
+`parseforge.naming` directly. Anything not in `parseforge.api.__all__` is internal
+and may change without notice.
+
 ## Reference
 
 - [Documentation site](https://geeks-trident-llc.github.io/parseforge/) ([source](./docs/index.md))

{parseforge-0.2.10 → parseforge-0.3.0}/SPEC.md

@@ -79,7 +79,7 @@ Keep the timestamp+shortid directories (not `result1..N`) — chronological orde
 | `derive/template.textfsm` | Cleaned, DSL-compiled TextFSM template candidate (`.textfsm` extension — recognized by TextFSM tooling/linters, unlike `textfsm.template`) |
 | `derive/readable-dsl.txt` | Human-readable description of what the template captures |
 | `derive/recognizers.txt` | Heuristics/signatures for detecting this output type at runtime |
-| `summary.json` | Everything else about the run: `created_at`/`ended_at`/`duration_ms`, `passed`, `error` (when `passed` is false), `metadata` (project/username/email/description), `command_info` (vendor/family/os/version/device_type/command), `usage` (naming + generation token counts/cost), and `provider_info` (the generation provider/model) |
+| `summary.json` | Everything else about the run: `created_at`/`ended_at`/`duration_ms`, `passed`, `error` (when `passed` is false), `metadata` (project/username/email/description), `command_info` (vendor/family/os/version/device_type/command), `usage` (naming + generation token counts), and `provider_info` (the generation provider/model) |
 
 ### 3.2 `integration/` (no human review yet)
 
@@ -180,4 +180,4 @@ Where a fourth tier is tempting but better handled as **metadata instead of a ne
 - Do you want a **registry/index file** (e.g. `catalog.json`) at the repo root listing every `<vendor>/<family>/<os>/<cli-name>` combination that exists, plus its authoritative status, for fast lookup without walking the filesystem?
 - What **confidence threshold** (match-rate %, sample count minimum) should gate auto-promotion vs. human review in step 9 — worth making this configurable per-project rather than hardcoded?
 - Should `recognizers.txt` support **one-of-many matching** from day one (per the multi-variant note in §6), or is that a v2 concern?
-- What's the **LLM provider/model** for generation — worth pinning per-project so `summary.json`'s usage costs are comparable across runs?
+- What's the **LLM provider/model** for generation — worth pinning per-project so `summary.json`'s token usage is comparable across runs?

parseforge-0.3.0/parseforge/__init__.py

@@ -0,0 +1,96 @@
+__version__ = "0.3.0"
+version = __version__
+
+from .api import (  # noqa: E402
+    DEFAULT_STORE_ROOT,
+    CliContext,
+    DeviceConnection,
+    DeviceKey,
+    DriftCheckResult,
+    DriftGate,
+    GenerationResult,
+    GenerationTokenUsage,
+    GroupEvaluation,
+    LLMCLIResponse,
+    LLMProviderConfig,
+    Mode,
+    NamingResolution,
+    NamingTokenUsage,
+    ParseResult,
+    PromotionDecision,
+    PromotionGate,
+    PromotionMetadata,
+    PromotionMode,
+    PromotionRunResult,
+    Reference,
+    ReferenceGroup,
+    ReferenceVariant,
+    RegexBuilder,
+    Sampler,
+    TrialMetadata,
+    TrialResult,
+    UserReviewedRequest,
+    build_integration,
+    build_reference_summary,
+    check_drift,
+    cli_name,
+    decide_promotion,
+    discover_device_keys,
+    evaluate_cases,
+    generate,
+    parse,
+    promote_auto,
+    promote_user_reviewed,
+    resolve_cli_name,
+    run_command_pipeline,
+    sample,
+    write_reference_summary,
+)
+
+__all__ = [
+    "version",
+    "__version__",
+    "cli_name",
+    "resolve_cli_name",
+    "NamingResolution",
+    "CliContext",
+    "RegexBuilder",
+    "LLMCLIResponse",
+    "NamingTokenUsage",
+    "sample",
+    "DeviceConnection",
+    "Sampler",
+    "generate",
+    "GenerationResult",
+    "GenerationTokenUsage",
+    "parse",
+    "ParseResult",
+    "run_command_pipeline",
+    "LLMProviderConfig",
+    "TrialMetadata",
+    "TrialResult",
+    "Mode",
+    "build_integration",
+    "build_reference_summary",
+    "write_reference_summary",
+    "Reference",
+    "ReferenceGroup",
+    "ReferenceVariant",
+    "promote_auto",
+    "promote_user_reviewed",
+    "decide_promotion",
+    "evaluate_cases",
+    "PromotionGate",
+    "PromotionMetadata",
+    "UserReviewedRequest",
+    "GroupEvaluation",
+    "PromotionRunResult",
+    "PromotionDecision",
+    "PromotionMode",
+    "check_drift",
+    "DriftGate",
+    "DriftCheckResult",
+    "DEFAULT_STORE_ROOT",
+    "DeviceKey",
+    "discover_device_keys",
+]

parseforge-0.3.0/parseforge/api.py

@@ -0,0 +1,127 @@
+"""Public Python API — the single place to import parseforge's stable,
+supported surface from. Mirrors textfsm-ai's own api.py convention
+(https://github.com/Geeks-Trident-LLC/textfsm-ai): one entry point per
+pipeline stage (SPEC.md §5), plus the types each one returns or accepts.
+
+Provider-specific naming builders (``AnthropicRegexBuilder``,
+``OCIRegexBuilder``, ...) aren't re-exported here — they're already a
+clean, documented import path via :mod:`parseforge.naming` directly, and
+listing all eighteen here would bloat this module without adding
+anything. Anything not listed in ``__all__`` (module-internal helpers,
+provider implementation details, CLI plumbing) isn't part of the public
+API and may change without notice.
+
+``naming``'s and ``generation``'s ``TokenUsage`` classes are separate
+types that happen to share a name (naming makes one call per cache
+miss; generation's is already accumulated across every LLM call in its
+own pipeline, see ``GenerationResult.usage``) — aliased here as
+``NamingTokenUsage``/``GenerationTokenUsage`` to avoid the collision,
+the same convention this package's own test suite already uses.
+"""
+
+from __future__ import annotations
+
+from .drift import DriftCheckResult, DriftGate, check_drift
+from .generation import GenerationResult, generate
+from .generation import TokenUsage as GenerationTokenUsage
+from .integration import (
+    Reference,
+    ReferenceGroup,
+    ReferenceVariant,
+    build_integration,
+    build_reference_summary,
+    write_reference_summary,
+)
+from .naming import (
+    CliContext,
+    LLMCLIResponse,
+    NamingResolution,
+    RegexBuilder,
+    cli_name,
+    resolve_cli_name,
+)
+from .naming import TokenUsage as NamingTokenUsage
+from .paths import DEFAULT_STORE_ROOT, DeviceKey, discover_device_keys
+from .pipeline import (
+    LLMProviderConfig,
+    Mode,
+    TrialMetadata,
+    TrialResult,
+    run_command_pipeline,
+)
+from .promotion import (
+    GroupEvaluation,
+    PromotionDecision,
+    PromotionGate,
+    PromotionMetadata,
+    PromotionMode,
+    PromotionRunResult,
+    UserReviewedRequest,
+    decide_promotion,
+    evaluate_cases,
+    promote_auto,
+    promote_user_reviewed,
+)
+from .sampling import DeviceConnection, Sampler, sample
+from .validation import ParseResult, parse
+
+__all__ = [
+    # Naming (SPEC.md §2) — resolve a raw CLI command to its canonical
+    # cli-name, cached after the first LLM call.
+    "cli_name",
+    "resolve_cli_name",
+    "NamingResolution",
+    "CliContext",
+    "RegexBuilder",
+    "LLMCLIResponse",
+    "NamingTokenUsage",
+    # Sampling (SPEC.md §3) — capture raw command output from a device.
+    "sample",
+    "DeviceConnection",
+    "Sampler",
+    # Generation (SPEC.md §5 steps 5-6) — sample -> candidate TextFSM
+    # template, via textfsm-ai's delivery pipeline.
+    "generate",
+    "GenerationResult",
+    "GenerationTokenUsage",
+    # Validation (SPEC.md §5 step 7) — self-validate a template against
+    # its own sample.
+    "parse",
+    "ParseResult",
+    # Pipeline orchestration (SPEC.md §5) — one call runs steps 1-7
+    # (naming -> sampling -> generation -> validation) for a single trial.
+    "run_command_pipeline",
+    "LLMProviderConfig",
+    "TrialMetadata",
+    "TrialResult",
+    "Mode",
+    # Integration (SPEC.md §5 step 8) — cluster trials by output schema.
+    "build_integration",
+    "build_reference_summary",
+    "write_reference_summary",
+    "Reference",
+    "ReferenceGroup",
+    "ReferenceVariant",
+    # Promotion (SPEC.md §5 step 9) — auto-promote groups that clear
+    # their gate; queue everything else for human review.
+    "promote_auto",
+    "promote_user_reviewed",
+    "decide_promotion",
+    "evaluate_cases",
+    "PromotionGate",
+    "PromotionMetadata",
+    "UserReviewedRequest",
+    "GroupEvaluation",
+    "PromotionRunResult",
+    "PromotionDecision",
+    "PromotionMode",
+    # Drift monitoring (SPEC.md §5 step 11) — check an authoritative
+    # template against new production samples.
+    "check_drift",
+    "DriftGate",
+    "DriftCheckResult",
+    # Store-root layout helpers.
+    "DEFAULT_STORE_ROOT",
+    "DeviceKey",
+    "discover_device_keys",
+]