Pontos de entrada CLI e API.

ContractForge expõe um pequeno núcleo CLI e CLIs de propriedade do adaptador. O núcleo valida e planeja a semântica; adaptadores renderizam ou executam comportamento nativo.

Núcleo CLI

contractforge validate path/to/table.ingestion.yaml
contractforge validate-bundle contracts/silver/s_customers
contractforge connectors list
contractforge connectors show jdbc incremental_files

O CLI principal não deve exigir SDKs de plataforma.

Adaptador Databricks CLI

contractforge-databricks render contracts/silver/s_customers
contractforge-databricks deploy-project project.yaml --target dev
contractforge-databricks deploy-project project.yaml --target dev --run
contractforge-databricks deploy-project project.yaml --render-bundle --force-render --target dev
contractforge-databricks render-project-bundle project.yaml --output databricks.yml --force
contractforge-databricks deploy-bundle databricks.yml --target dev --run

Os comandos do adaptador podem exigir dependências específicas da plataforma, configuração do espaço de trabalho ou credenciais. A implantação do Databricks usa Databricks Asset Bundles e Databricks CLI; o core não implanta jobs.

Adaptador AWS CLI

contractforge-aws plan contracts/silver/s_customers.ingestion.yaml
contractforge-aws render contracts/silver/s_customers.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws publish-s3 contracts/silver/s_customers.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws deploy contracts/silver/s_customers.ingestion.yaml --environment environments/prod.aws.yaml
contractforge-aws deploy-project project.yaml --dry-run --summary-only
contractforge-aws deploy-project project.yaml --run --wait --audit-evidence --athena-output-location s3://bucket/athena-results/
contractforge-aws deploy-project project.yaml --dry-run --render-orchestration --summary-only
contractforge-aws deploy-project project.yaml --deploy-orchestration --summary-only
contractforge-aws deploy-project project.yaml --deploy-orchestration --wait-orchestration --summary-only
contractforge-aws deploy-project project.yaml --deploy-orchestration --wait-orchestration --record-cost-evidence --athena-output-location s3://bucket/athena-results/

A implantação do AWS publica contratos/artefatos de tempo de execução no S3 e cria ou atualiza trabalhos Glue. O trabalho Glue é um bootstrap genérico que carrega o Biblioteca de tempo de execução contractforge-aws e contrato YAML em tempo de execução; o o caminho padrão não é o código de ingestão gerado por contrato.

Use deploy-project para projetos de ingestão de estilo de repositório com project.yaml.execution_order. Ele implanta cada contrato AWS em ordem e pode iniciar/aguardar execuções do Glue. Use --dry-run para validar o planejamento/renderização localmente e compilar Glue Python gerado sem chamadas AWS API. Passos com expected_result: failed pode ser aceito com --accept-expected-failures para testes de observabilidade de falhas. --audit-evidence executa o Athena padrão auditoria da tabela de controle após execuções esperadas do Glue.

Use --render-orchestration ou --deploy-orchestration quando o projeto precisar também tem um projeto persistente AWS nativo DAG. O adaptador renderiza Step Funções mais EventBridge Scheduler opcional do project.yaml; o núcleo faz não conheço esses serviços. Use --wait-orchestration para iniciar e aguarde o Execução do Step Functions em vez de executar cada tarefa Glue diretamente.

ContractForge AI CLI

contractforge-ai plan-project \
  --intent "Create an AWS Glue bronze ingestion project from s3://landing/orders into analytics.bronze.b_orders using append." \
  --schema schemas/orders.json \
  --format markdown

contractforge-ai generate-project \
  --target aws-glue-iceberg \
  --schema schemas/orders.json \
  --project-name orders_aws \
  --connector s3 \
  --source-path s3://landing/orders \
  --target-catalog analytics \
  --target-schema bronze \
  --target-table b_orders \
  --output-dir generated/orders-aws

contractforge-ai validate-project-structure generated/orders-aws --adapter aws --format html > project_validation.html

contractforge-ai route-task \
  --intent "Summarize low-risk metadata improvements for this connector" \
  --knowledge-index .contractforge-ai/knowledge.json \
  --prefer-http-only \
  --format markdown

As metas de geração de projetos incluem contractforge-yaml, contractforge-python, databricks-dab, aws-glue-iceberg, snowflake-sql-warehouse, fabric-lakehouse, gcp-bigquery, dbt e classic-pyspark. Os alvos do adaptador geram projetos que priorizam o contrato com project.yaml, environments/<adapter>.environment.yaml, connections/source.yaml e contratos divididos em contracts/<adapter>/....

As dicas da plataforma do planejador vêm de palavras explícitas de plataforma ou serviço de plataforma, não apenas locais de armazenamento. s3://... seleciona o conector s3 mas não forçar AWS; iceberg pode descrever o formato da tabela sem forçar o adaptador AWS. Se nenhuma plataforma for nomeada e vários adaptadores suportarem o conector, o planejamento pode recomendar vários destinos de adaptador para a mesma intenção de contrato. Os alvos de geração explícitos também são dicas determinísticas da plataforma: --target aws-glue-iceberg, --target snowflake-sql-warehouse, --target fabric-lakehouse, --target gcp-bigquery e --target databricks-dab adiciona a estrutura de ambiente correspondente, enquanto o os contratos de ingestão permanecem canônicos.

O ambiente AWS gerado usa espaços reservados de revisão sintaticamente válidos para campos validados pelo planejador, como s3://review-required-contractforge-artifacts/project/. Substitua aqueles por reais artefato, armazém, função IAM e locais de roda antes da implantação. O o adaptador ainda possui implantação por meio de contractforge-aws; A geração de IA faz não coloca o comportamento do AWS no núcleo ou na lógica de ingestão gerada por contrato.

route-task --prefer-http-only pode reduzir a pressão de dependência do SDK para baixo risco fluxos de trabalho de consultoria. Não é um mecanismo de downgrade: planejamento de projetos, a geração de contratos e os fluxos de trabalho de artefatos implantáveis ​​ainda exigem suporte a saída estruturada porque sua saída pode afetar a ingestão real comportamento.

validate-project-structure --format html é o resultado de revisão preferido para pastas completas do projeto. Ele renderiza descobertas e evidências de planejamento do adaptador como cartões legíveis e usa READY_WITH_WARNINGS para projetos somente de aviso que remain ready=true.

Núcleo Python API

Função ou tipo	Usar
validate_contract	Valide um mapeamento de contrato de ingestão.
load_contract_bundle	Carregue arquivos divididos de ingestão, anotações, operações, acesso e ambiente.
semantic_contract_from_mapping	Normalize um contrato validado em uma intenção semântica imutável.
PlatformCapabilities	Declare o que uma plataforma pode preservar.
plan_contract	Match semantic requirements against capabilities.
PlanningResult	Status de retorno, plano, bloqueadores e avisos.

from contractforge_core.contracts import validate_contract, semantic_contract_from_mapping
from contractforge_core.capabilities import PlatformCapabilities
from contractforge_core.planner import plan_contract

contract = validate_contract({
    "source": {"type": "table", "table": "main.raw.orders"},
    "target": {"catalog": "main", "schema": "bronze", "table": "b_orders"},
    "mode": "append",
})

semantic = semantic_contract_from_mapping(contract)
result = plan_contract(
    semantic,
    PlatformCapabilities(platform="example", supports_append=True, evidence_stores=("audit",)),
)
print(result.status)

Databricks Python API

Função ou tipo	Usar
plan_databricks_contract	Planeje um contrato com base nos recursos do Databricks.
render_databricks_contract	Produza artefatos Databricks nativos.
ingest_databricks_bundle	Execute um pacote de contrato dividido em Databricks.
deploy_databricks_project	Valide/implante/execute o Databricks Asset Bundle declarado por project.yaml.
deploy_databricks_bundle	Valide/implante/execute um diretório Databricks Asset Bundle ou databricks.yml.
render_databricks_project_bundle	Renderize um objeto Databricks Asset Bundle a partir de metadados de agendamento/dependência project.yaml.
render_databricks_project_bundle_file	Renderize e grave databricks.yml de um arquivo de projeto.
DatabricksEnvironment	Descreva o tempo de execução e as dicas de implantação do Databricks.
DatabricksIngestOptions	Passe opções de tempo de execução, como catálogo/esquema de evidências.

from contractforge_databricks import deploy_databricks_project, render_databricks_contract

artifacts = render_databricks_contract("contracts/bronze/b_orders.ingestion.yaml")
print(artifacts.status)

deployment = deploy_databricks_project("project.yaml", profile="dbc-dev", target="dev", run=True)
print(deployment["status"])

AWS Python API

Função ou tipo	Usar
plan_aws_contract	Planeje um contrato com base nos recursos AWS Glue/Iceberg.
render_aws_contract	Produza artefatos de revisão AWS, scripts Glue e cargas úteis de implantação.
publish_aws_contract_artifacts_to_s3	Publique artefatos renderizados em S3.
deploy_aws_contract_to_glue	Renderize, publique e crie ou atualize um trabalho Glue.
AWSEnvironment	Interprete as configurações do ambiente AWS, como banco de dados de evidências e artefato URI.

from contractforge_aws import deploy_aws_contract_to_glue

deployment = deploy_aws_contract_to_glue(contract, environment=environment)
print(deployment.job_name)

Campos de contrato comuns

Field	Significado
source	Intenção de origem, referência de conexão, tabela/consulta/caminho ou opções específicas do conector.
source.system	Rótulo do sistema de origem registrado em evidência.
source.ref / source.table_ref	Referência lógica de layer.table para outra tabela gerenciada por ContractForge.
target	Identidade física canônica de catálogo/esquema/tabela.
layer	Camada lógica usada para classificação e observabilidade.
mode	Escreva semântica como anexar, substituir, upsert, hash diff, histórico ou instantâneo.
schema_policy	Manipulação do esquema de destino.
quality_rules	Regras de validação e quarentena.
transform / shape	Preparação portátil antes de escrever.
extensions.<adapter>	Opções de propriedade do adaptador que não são semânticas centrais portáteis.

Use campos target aninhados e blocos de extensão do adaptador na documentação e nos exemplos. Os campos de destino ou plataforma legados de nível superior não fazem parte intencionalmente do contrato canônico.