AGENT SKILL

vibey-bootstrap-core

Use when installing or consuming the vibey-bootstrap Python library (v4.0.0) and its v1 core. Covers pip install and the optional-extras matrix (fastapi, servicebus, sumologic, logging-all, db, email, http, documentdb, governance, aks, vibey-bootstrap scaffold, all, etc.), the 4-phase bootstrap that breaks the logging↔configuration circular dependency, initialize_application / get_bootstrap_logger, configuration precedence and the local-override rule, EnhancedConfigRepository, SecretsRepository, Key Vault references, DI interfaces, RepositoryError/ConfigurationError/KeyVaultError, and v1 environment variables (APPLICATIONINSIGHTS_CONNECTION_STRING, AZURE_APP_CONFIGURATION_CONNECTION_STRING, AZURE_KEY_VAULT_URL, LOG_LEVEL). Triggers on vibey-bootstrap, vibey_bootstrap, Azure Functions/container app startup config, App Configuration + Key Vault loading, load_to_environ, or installing the bootstrap extras from the vibey distribution.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 5
Forks
3

01 前言 Front Matter

name
vibey-bootstrap-core
description
Use when installing or consuming the vibey-bootstrap Python library (v4.0.0) and its v1 core. Covers pip install and the optional-extras matrix (fastapi, servicebus, sumologic, logging-all, db, email, http, documentdb, governance, aks, vibey-bootstrap scaffold, all, etc.), the 4-phase bootstrap that breaks the logging↔configuration circular dependency, initialize_application / get_bootstrap_logger, configuration precedence and the local-override rule, EnhancedConfigRepository, SecretsRepository, Key Vault references, DI interfaces, RepositoryError/ConfigurationError/KeyVaultError, and v1 environment variables (APPLICATIONINSIGHTS_CONNECTION_STRING, AZURE_APP_CONFIGURATION_CONNECTION_STRING, AZURE_KEY_VAULT_URL, LOG_LEVEL). Triggers on vibey-bootstrap, vibey_bootstrap, Azure Functions/container app startup config, App Configuration + Key Vault loading, load_to_environ, or installing the bootstrap extras from the vibey distribution.

03 SKILL.md 正文

vibey-bootstrap is the library formerly published as azure-bootstrap (renamed in 4.0.0: package vibey-bootstrap, import vibey_bootstrap, CLI vibey-bootstrap; azbootstrap remains as a deprecated alias). Feature-tier labels below (v2 primitives, v3 modules) are historical and unchanged.

Azure Bootstrap — Installation & v1 Core (4-phase bootstrap)

vibey-bootstrap solves the logging ↔ configuration circular dependency every Azure Functions / container app hits at startup (you need logging to report config loading, but App Insights logging needs config to initialize). On top of that v1 core, v2 adds a large, opt-in, framework-agnostic "cross-cutting layer": structured logging, correlation, tracing, counters, tiered alerts, an error vocabulary, ingress hardening, Service Bus plumbing, webhook auth, AI usage tracking, health probes, a v2.1 logging-transport layer (console / App Insights / Sumo Logic), and v4.0.0 adds seven more logging transports plus DB/outbox, email, hardened HTTP, AKS runtime, governance, and an vibey-bootstrap scaffold CLI — all opt-in behind pip extras.

vibey-bootstrap is a pure Python package. It ships inside the vibey distribution on PyPI (vibey ADR-0037) and has no JavaScript/TypeScript distribution — you cannot npm install or import it from a Next.js app. (For TS, see the vibey-bootstrap-typescript skill: HTTP client integration with a Python backend, and porting the patterns to TypeScript.)

Compatibility: the source and the distribution that ships it support Python ≥ 3.12. Distribution: pip install vibey-engine (PyPI, MIT) — there is no separate vibey-bootstrap project (vibey ADR-0037). v4.0.0 is additive — every v1/v2 import path, symbol, signature, and default is unchanged; opt into new extras and env flags. See MIGRATING-TO-V3.md.

1. Installation & extras

pip install vibey-engine                     # the whole family; vibey_bootstrap importable
pip install 'vibey-engine[azure]'            # App Configuration + Key Vault + App Insights
pip install 'vibey-engine[bootstrap-all]'    # every optional dependency any extra below needs

Extra names. The matrix below lists the extras as vibey-bootstrap's own pyproject.toml declares them, and they still select what each feature needs when the package is installed from the tree. On the vibey-engine package there is no per-feature successor spelling: the replacements are the two aggregates above (vibey ADR-0037).

Core dependencies (always installed)

azure-appconfiguration-provider>=1.0.0
azure-keyvault-secrets>=4.7.0
azure-identity>=1.15.0
azure-monitor-opentelemetry>=1.2.0
opentelemetry-api>=1.22.0
# Pinned minimums for CVE remediation:
azure-core>=1.38.0     # CVE-2026-21226
filelock>=3.20.3       # CVE-2025-68146, CVE-2026-22701
urllib3>=2.7.0         # CVE-2026-21441 + CVE-2026-44431/44432
cryptography>=48.0.1,<49  # GHSA-537c-gmf6-5ccf (via azure-identity/msal)
pyjwt>=2.13.0          # PYSEC-2026-175..179 (via msal)

Optional extras matrix

Source of truth: pyproject.toml. Many extras are empty markers ([]): the code is stdlib-only and already importable without the extra — the extra exists for discoverability / intent, and only pulls real dependencies where a third-party package is genuinely required.

Extra Installs What it unlocks
fastapi fastapi>=0.110 fastapi_middleware, webhook route, API-key dep, fastapi_rate_limit
servicebus azure-servicebus>=7.11 servicebus.* consumer/DLQ helpers
sb-lock — (uses servicebus) sb_lock message-lock renewal
scheduler apscheduler>=3.10 scheduler.parse_cron_trigger
retry tenacity>=8.0 retry.build_retry + Azure/AI presets
pdf-safety pypdf>=6.13.3 pdf_safety.sanitize_pdf_for_passthrough
sumologic requests>=2.32.0 SumoLogicHandler transport
panther requests>=2.32.0 Panther SIEM transport
bloblog azure-storage-blob>=12.19 Blob Storage log transport
sqllog sqlalchemy>=2.0 SQL table log transport
nosqllog pymongo>=4.6 Mongo/Cosmos log transport
nosqllog-cosmos azure-cosmos>=4.5 Cosmos-native log transport
adxlog azure-kusto-ingest, azure-kusto-data ADX log transport
eventhubslog azure-eventhub>=5.11 Event Hubs log transport
logging-all all transport deps above every logging transport
transports — (stdlib) transport registry + console/app-insights
alerts — (stdlib) tiered alert dispatcher
health — (stdlib) readiness probes
heartbeat — (stdlib) heartbeat + consumer watchdog
config-refresh — (stdlib) refresh_log_flags
ingress — (stdlib) 4-gate attachment classifier
ratelimit — (stdlib) TokenBucket + presets
notify — (stdlib) two-tier notification builders
subscription — (stdlib) resource renewal loop
auth — (uses fastapi) webhook + API-key guards
identity — (azure-identity in core) build_credential
audit — (stdlib) build_audit_extra
failclose — (stdlib) require_env / optional_env / fail_open_env
openai — (stdlib) AI usage tracker
tokens — (stdlib) HMAC action tokens
metrics — (stdlib) build_metrics_snapshot
db sqlalchemy>=2.0, alembic>=1.13 get_db, outbox, Alembic helpers
email azure-communication-email>=1.0 AcsEmailSender
http requests>=2.32.0 build_session(), request_with_retry()
http-async httpx>=0.27 build_async_client(), async_request_with_retry()
documentdb pymongo>=4.6 mongo_client_from_env()
governance — (stdlib) budget_guard(), track_usage()
aks — (stdlib) build_info(), install_sigterm_handler(), leader election
all fastapi, servicebus, apscheduler, requests, blob, sqlalchemy, alembic, pymongo, ACS email, kusto, eventhub, httpx aggregate of all third-party deps
dev / test tooling / test deps development & CI

The vibey-bootstrap console script (vibey-bootstrap list, vibey-bootstrap scaffold) ships with the core install — no extra required. Templates live under vibey_bootstrap.contrib.

2. Python: the v1 core (4-phase bootstrap)

The problem and the solution

Configuration loading wants logging to report progress; App Insights logging wants configuration to initialize. The library breaks the cycle in four phases:

  1. Console logging — works immediately (always).
  2. Telemetry from env — try App Insights from APPLICATIONINSIGHTS_CONNECTION_STRING.
  3. Configuration load — Azure App Configuration + Key Vault → os.environ.
  4. Telemetry upgrade — if the connection string only arrived via config, upgrade to App Insights now.

Quick start (the canonical pattern)

import os
from vibey_bootstrap import initialize_application, get_bootstrap_logger

logger = get_bootstrap_logger(__name__)     # works before bootstrap completes
config_repo = initialize_application()       # runs all four phases
# Every App Config + Key Vault value is now in os.environ:
db_host = os.getenv("DATABASE_HOST")

Configuration precedence & the local-override rule

Lookup order, highest priority first:

  1. Environment variables (os.environ) — local overrides always win
  2. In-process cache (prior get_value() results)
  3. Azure App Configuration (Key Vault references auto-resolved)
  4. Key Vault (direct, via the secrets repository)
  5. Default values

load_to_environ() never overwrites an existing os.environ key — so anything set by local.settings.json (or your shell) survives, and only new remote keys are added. App Config can store Key Vault references (a JSON {"uri": "...vault.../secrets/..."}); the provider resolves them transparently, so os.getenv("DATABASE_PASSWORD") returns the actual secret, not the URI.

API reference — entry points

from vibey_bootstrap import (
    initialize_application, get_bootstrap_logger,
    ensure_bootstrap_logging, create_enhanced_config_repository,
)
Symbol Signature Behavior
initialize_application (secrets_repository: SecretsRepositoryInterface | None = None) -> EnhancedConfigRepositoryInterface Runs the 4-phase bootstrap; loads all config to os.environ; caches the repo for refresh_setting(). Raises RuntimeError on unrecoverable failure.
get_bootstrap_logger (name: str) -> logging.Logger A logger usable immediately; auto-configures bootstrap logging on first call.
ensure_bootstrap_logging () -> None Idempotent bootstrap-logging setup.
create_enhanced_config_repository (app_config_connection_string=None, secrets_repository=None, auto_load_to_environ=False) -> EnhancedConfigRepositoryInterface Factory for the config repository.

API reference — classes

from vibey_bootstrap import (
    ApplicationBootstrap, BootstrapLogger, ExtraFieldsFormatter,
    TelemetryManager, telemetry_manager,
    EnhancedConfigRepository, SecretsRepository,
)
  • ApplicationBootstrap(secrets_repository=None) — orchestrator. .initialize() runs the four phases and returns the repo; .get_config_repository(), .is_bootstrap_completed().

  • BootstrapLogger — .configure_bootstrap_logging(level=None) (class method; level falls back to LOG_LEVEL env, then INFO).

  • ExtraFieldsFormatter — logging.Formatter that appends extra={} fields to each line. (v1 lives in services.bootstrap_logging; a v2 variant lives in vibey_bootstrap.logging — see the vibey-bootstrap-primitives skill.)

  • TelemetryManager / telemetry_manager (singleton) — .configure(connection_string=None, allow_reconfigure=False) -> bool and .try_upgrade_from_config(config_repository) -> bool. Best-effort: always falls back to console logging rather than raising.

  • EnhancedConfigRepository — key methods:

    Method Purpose
    get_value(key, default=None) -> str | None env → cache → App Config → Key Vault → default
    get_secret_value(key, default=None) -> str | None direct Key Vault lookup
    get_all_values() -> dict[str, str] merged view (env wins)
    load_to_environ() -> int populate os.environ; returns count of new keys
    refresh() -> None clear cache + reload (used by refresh_setting)
    get_repository_metrics() -> dict availability + counts
    is_app_config_available() / is_key_vault_available() feature probes
  • SecretsRepository(vault_url=None) — get_secret, set_secret, delete_secret, list_secrets, is_available (reads AZURE_KEY_VAULT_URL).

Interfaces (DI / type hints) and exceptions

from vibey_bootstrap import (
    ApplicationBootstrapInterface, BootstrapLoggerInterface,
    TelemetryManagerInterface, EnhancedConfigRepositoryInterface,
    SecretsRepositoryInterface,
    RepositoryError, ConfigurationError, KeyVaultError,   # ConfigurationError, KeyVaultError subclass RepositoryError
)

v1 environment variables

Variable Used by Purpose
APPLICATIONINSIGHTS_CONNECTION_STRING TelemetryManager App Insights telemetry
AZURE_APP_CONFIGURATION_CONNECTION_STRING EnhancedConfigRepository App Configuration endpoint
AZURE_APPCONFIG_ENDPOINT health probe / AAD auth App Config endpoint (credential-based)
AZURE_KEY_VAULT_URL SecretsRepository Key Vault endpoint
LOG_LEVEL bootstrap + telemetry logging DEBUG/INFO/WARNING/ERROR (default INFO)
FUNCTIONS_WORKER_RUNTIME bootstrap logging presence triggers Azure-Functions log setup

04 同仓库更多 Skills

the-vibey-project
the-vibey-project/vibey

white-paper-writing

Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks "how should I structure this" for a long-form document.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-technical-mechanics

Use when editing or writing prose at a technical/mechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.

★ 5
the-vibey-project
the-vibey-project/vibey

prose-mechanics

Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate/Jamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix "AI-sounding" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.

★ 5
the-vibey-project
the-vibey-project/vibey

narrative-structure

Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or "how should I structure this story/pitch/presentation" request.

★ 5
the-vibey-project
the-vibey-project/vibey

legal-brief-writing

Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic/neurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.

★ 5
the-vibey-project
the-vibey-project/vibey

journal-publishability-criteria

Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs/paper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.

★ 5