estruturacao

estruturacao

Estruturação de textos com LLMs — extrai campos JSON conforme um schema.

Modo nuvem

Roda na infra do escritório (GPT-4.1-mini via Azure OpenAI). Os modelos self-host em GPU A100 (gpt-oss-20b, gemma-4-26b-it) foram descontinuados por custo proibitivo no padrão de uso atual.

Modo local

Cliente OpenAI-compatível: aceita OpenAI, Azure OpenAI, Ollama (default http://localhost:11434/v1) ou qualquer servidor /v1/chat/completions. O usuário traz a própria chave/URL. Desde a v0.5.0 a chamada ao LLM e a montagem do prompt vivem em labdados_core.estruturacao — o mesmo código rodado pelo backend (services/structuring), garantindo que prompt e parsing não divirjam.

.. note:: Mudança de comportamento na v0.5.0: o schema passa a ser injetado na mensagem user (junto do texto), não mais na system. Isso alinha com o backend e funciona melhor com response_format=json_schema. Se o seu prompt depender da formulação antiga, instrua o LLM via prompt_sistema ou abra uma issue.

Functions

Name	Description
estruturacao	Extrai campos estruturados (JSON) a partir de textos.

estruturacao

estruturacao.estruturacao(
    arquivos,
    *,
    schema,
    prompt_sistema='',
    saida=None,
    api_key=None,
    modelo='gpt-4.1-mini',
    coluna_texto='',
    temperatura=0.0,
    max_tokens=4096,
    local=False,
    base_url_local='http://localhost:11434/v1',
    api_key_local='ollama',
    modelo_local='llama3.1',
    client=None,
    progress=True,
)

Extrai campos estruturados (JSON) a partir de textos.

Parameters

Name	Type	Description	Default
arquivos	PathLike | list[PathLike]	.txt, .md, .docx, .csv ou .xlsx. Para CSV/XLSX, cada linha vira um documento — use coluna_texto para indicar qual coluna contém o texto a estruturar.	required
schema	dict[str, Any] | str	JSON Schema (dict) ou string JSON. Define os campos extraídos e seus tipos. Mantenha simples — campos com description ajudam muito a LLM.	required
prompt_sistema	str	Instruções de contexto (qual o tipo de documento, o que ignorar…).	''
saida	PathLike | None	Pasta de saída. Cada documento gera um .json com a extração.	None
api_key	str | None	Chave de API do escritório (modo nuvem).	None
modelo	str	"gpt-4.1-mini" (default — único modelo nuvem disponível hoje). Os modelos self-host em GPU A100 (gpt-oss-20b, gemma-4-26b-it) foram descontinuados por custo.	'gpt-4.1-mini'
coluna_texto	str	Para CSV/XLSX: nome da coluna que contém o texto a ser estruturado. Vazio = concatena todas as colunas da linha.	''
temperatura	float	0.0 para resultado determinístico (recomendado em extração).	0.0
max_tokens	int	Tamanho máximo da resposta JSON. Aumente se o JSON estiver sendo cortado.	4096
local	bool	Se True, chama um servidor OpenAI-compatível local. Default: Ollama em http://localhost:11434/v1.	False
base_url_local	str	Configuração do servidor local. Para Azure OpenAI, ajuste base_url_local e api_key_local. Para Ollama, mantenha os defaults e mude apenas modelo_local (ex.: "qwen2.5:7b").	'http://localhost:11434/v1'
api_key_local	str	Configuração do servidor local. Para Azure OpenAI, ajuste base_url_local e api_key_local. Para Ollama, mantenha os defaults e mude apenas modelo_local (ex.: "qwen2.5:7b").	'http://localhost:11434/v1'
modelo_local	str	Configuração do servidor local. Para Azure OpenAI, ajuste base_url_local e api_key_local. Para Ollama, mantenha os defaults e mude apenas modelo_local (ex.: "qwen2.5:7b").	'http://localhost:11434/v1'
client	Client | None	Cliente reaproveitado (modo nuvem).	None
progress	bool	Spinner no stderr.	True

Returns

Name	Type	Description
	Path	Pasta de saída.

Examples

Modo nuvem com schema simples:

>>> import labdados
>>> labdados.estruturacao(
...     arquivos="acordaos.csv",
...     coluna_texto="ementa",
...     api_key="sk_lab_...",
...     prompt_sistema="Você está extraindo decisões judiciais sobre direito do consumidor.",
...     schema={
...         "type": "object",
...         "properties": {
...             "autor": {"type": "string"},
...             "reu": {"type": "string"},
...             "valor_causa": {"type": "number"},
...             "procedente": {"type": "boolean"},
...         },
...         "required": ["autor", "reu"],
...     },
... )

Modo local com Ollama:

>>> labdados.estruturacao(
...     arquivos="textos/",
...     schema={"type": "object", "properties": {"resumo": {"type": "string"}}},
...     local=True,
...     modelo_local="qwen2.5:7b",
... )