Guia de Uso - APIs `/feature-store`

Base URL: https://csuite.internut.com.br/feature-store

Documentação Swagger: https://csuite.internut.com.br/feature-store/docs

📋 Índice

Visão Geral
Feature Definitions API
Feature Values API
Feature Compute API
Feature Groups API
Feature Lineage API
Sync API
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite Feature Store é um Feature Store centralizado para o ecossistema C-Suite. Armazena, versiona e serve features de forma consistente e eficiente.

Objetivos

Centralização: Features em um único lugar
Reutilização: Evita recálculo desnecessário
Versionamento: Controle de versões de features
Performance: Cache distribuído (Redis + MySQL)
Consistência: Mesmas features para treinamento e produção

Componentes

FeatureDefinition: Definições de features
FeatureValue: Valores computados (com cache)
FeatureGroup: Grupos de features relacionadas
FeatureLineage: Rastreamento de origem e dependências
FeatureComputationLog: Logs de computação

Integrações

Feature Service (4C): Usa como fonte de dados
Scoring Service: Consome features do store
ML Pipeline: Usa features consistentes para treinamento
Redis: Cache distribuído para performance

2. Feature Definitions API

Base Path: /definitions

2.1 Listar Definições

Endpoint: GET /definitions

Descrição: Lista todas as definições de features.

Parâmetros de Query:
- status (string, padrão: active) - Filtrar por status (active, inactive, deprecated)

Exemplo:

# Todas as features ativas
curl "https://csuite.internut.com.br/feature-store/definitions"

# Features inativas
curl "https://csuite.internut.com.br/feature-store/definitions?status=inactive"

Resposta:

[
  {
    "id": 1,
    "name": "recency_days",
    "description": "Dias desde a última compra",
    "feature_type": "numeric",
    "version": "v1",
    "schema": {
      "type": "float",
      "min": 0,
      "max": null
    },
    "computation_logic": "DATEDIFF(CURDATE(), last_purchase_date)",
    "status": "active",
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  },
  {
    "id": 2,
    "name": "freq_90d",
    "description": "Frequência de compras nos últimos 90 dias",
    "feature_type": "numeric",
    "version": "v1",
    "status": "active",
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  }
]

2.2 Criar Definição

Endpoint: POST /definitions

Descrição: Cria nova definição de feature.

Request Body:

{
  "name": "value_90d",
  "description": "Valor total de compras nos últimos 90 dias",
  "feature_type": "numeric",
  "version": "v1",
  "schema": {
    "type": "float",
    "min": 0,
    "max": null
  },
  "computation_logic": "SELECT SUM(total) FROM orders WHERE customer_id = :entity_id AND order_date >= DATE_SUB(CURDATE(), INTERVAL 90 DAY)",
  "status": "active"
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/feature-store/definitions" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "value_90d",
    "description": "Valor total de compras nos últimos 90 dias",
    "feature_type": "numeric",
    "version": "v1",
    "schema": {
      "type": "float",
      "min": 0
    },
    "computation_logic": "SELECT SUM(total) FROM orders WHERE customer_id = :entity_id",
    "status": "active"
  }'

Resposta:

{
  "id": 3,
  "name": "value_90d",
  "description": "Valor total de compras nos últimos 90 dias",
  "feature_type": "numeric",
  "version": "v1",
  "schema": {
    "type": "float",
    "min": 0
  },
  "computation_logic": "SELECT SUM(total) FROM orders WHERE customer_id = :entity_id",
  "status": "active",
  "created_at": "2024-12-01T10:05:00Z",
  "updated_at": "2024-12-01T10:05:00Z"
}

Tipos de Features:
- numeric: Valores numéricos (int, float)
- categorical: Valores categóricos (string, enum)
- text: Texto livre
- boolean: Valores booleanos
- datetime: Datas e timestamps

Erros:
- 400: Feature já existe
- 422: Dados inválidos

2.3 Obter Definição

Endpoint: GET /definitions/{feature_name}

Descrição: Obtém definição específica de uma feature.

Parâmetros de Path:
- feature_name (string, obrigatório) - Nome da feature

Exemplo:

curl "https://csuite.internut.com.br/feature-store/definitions/recency_days"

Resposta:

{
  "id": 1,
  "name": "recency_days",
  "description": "Dias desde a última compra",
  "feature_type": "numeric",
  "version": "v1",
  "schema": {
    "type": "float",
    "min": 0
  },
  "computation_logic": "DATEDIFF(CURDATE(), last_purchase_date)",
  "status": "active",
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}

Erros:
- 404: Feature não encontrada

3. Feature Values API

Base Path: /values

3.1 Obter Valores de Features

Endpoint: POST /values

Descrição: Obtém valores de features para uma entidade (com cache).

Request Body:

{
  "entity_type": "customer",
  "entity_id": "12345",
  "feature_names": ["recency_days", "freq_90d", "value_90d"],
  "use_cache": true
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/feature-store/values" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "customer",
    "entity_id": "12345",
    "feature_names": ["recency_days", "freq_90d", "value_90d"],
    "use_cache": true
  }'

Resposta:

{
  "entity_type": "customer",
  "entity_id": "12345",
  "features": {
    "recency_days": 15,
    "freq_90d": 3,
    "value_90d": 1250.50
  },
  "computed_at": "2024-12-01T10:00:00Z",
  "from_cache": false
}

Campos do Request:
- entity_type: Tipo de entidade (customer, product, seller, etc.)
- entity_id: ID da entidade
- feature_names: Lista de nomes de features (opcional, se null retorna todas)
- use_cache: Se true, usa cache quando disponível (padrão: true)

Comportamento:
- Se feature_names não especificado, retorna todas as features ativas
- Se features não encontradas e feature_names não especificado, computa todas automaticamente
- Cache é usado quando use_cache=true e features estão em cache

4. Feature Compute API

Base Path: /compute

4.1 Computar Features

Endpoint: POST /compute

Descrição: Computa features para uma entidade (força recálculo se necessário).

Request Body:

{
  "entity_type": "customer",
  "entity_id": "12345",
  "feature_names": ["recency_days", "freq_90d"],
  "force_recompute": false
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/feature-store/compute" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "customer",
    "entity_id": "12345",
    "feature_names": ["recency_days", "freq_90d"],
    "force_recompute": false
  }'

Resposta:

{
  "entity_type": "customer",
  "entity_id": "12345",
  "features": {
    "recency_days": 15,
    "freq_90d": 3
  },
  "computation_time_ms": 45.2,
  "computed_at": "2024-12-01T10:05:00Z"
}

Campos do Request:
- entity_type: Tipo de entidade (customer, product, seller, etc.)
- entity_id: ID da entidade
- feature_names: Lista de nomes de features (opcional, se null computa todas ativas)
- force_recompute: Se true, força recálculo mesmo se cache existe (padrão: false)

Casos de Uso:
- Recálculo após mudança de dados
- Computação inicial de features
- Atualização forçada de cache
- Validação de features

5. Feature Groups API

Base Path: /groups

5.1 Listar Grupos

Endpoint: GET /groups

Descrição: Lista grupos de features.

Parâmetros de Query:
- category (string, opcional) - Filtrar por categoria

Exemplo:

# Todos os grupos
curl "https://csuite.internut.com.br/feature-store/groups"

# Grupos de uma categoria
curl "https://csuite.internut.com.br/feature-store/groups?category=rfm"

Resposta:

[
  {
    "id": 1,
    "name": "rfm_features",
    "description": "Features RFM (Recency, Frequency, Monetary)",
    "category": "rfm",
    "features": ["recency_days", "freq_90d", "value_90d"],
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  },
  {
    "id": 2,
    "name": "behavioral_features",
    "description": "Features comportamentais",
    "category": "behavior",
    "features": ["avg_order_value", "preferred_channel", "response_rate"],
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  }
]

5.2 Criar Grupo

Endpoint: POST /groups

Descrição: Cria novo grupo de features.

Parâmetros de Query:
- name (string, obrigatório) - Nome do grupo
- description (string, opcional) - Descrição do grupo
- category (string, opcional) - Categoria do grupo
- features (array, opcional) - Lista de nomes de features

Exemplo:

curl -X POST "https://csuite.internut.com.br/feature-store/groups?name=rfm_features&description=Features RFM&category=rfm&features=recency_days&features=freq_90d&features=value_90d"

Resposta:

{
  "id": 1,
  "name": "rfm_features",
  "description": "Features RFM (Recency, Frequency, Monetary)",
  "category": "rfm",
  "features": ["recency_days", "freq_90d", "value_90d"],
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}

Erros:
- 400: Grupo já existe

5.3 Obter Grupo

Endpoint: GET /groups/{group_name}

Descrição: Obtém grupo de features específico.

Parâmetros de Path:
- group_name (string, obrigatório) - Nome do grupo

Exemplo:

curl "https://csuite.internut.com.br/feature-store/groups/rfm_features"

Resposta:

{
  "id": 1,
  "name": "rfm_features",
  "description": "Features RFM (Recency, Frequency, Monetary)",
  "category": "rfm",
  "features": ["recency_days", "freq_90d", "value_90d"],
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}

Erros:
- 404: Grupo não encontrado

6. Feature Lineage API

Base Path: /lineage

6.1 Obter Lineage

Endpoint: GET /lineage/{feature_name}

Descrição: Obtém lineage (origem e dependências) de uma feature.

Parâmetros de Path:
- feature_name (string, obrigatório) - Nome da feature

Exemplo:

curl "https://csuite.internut.com.br/feature-store/lineage/rfm_score"

Resposta:

{
  "id": 1,
  "feature_name": "rfm_score",
  "source_type": "computed",
  "source_location": "feature_store",
  "dependencies": ["recency_days", "freq_90d", "value_90d"],
  "computation_script": "def compute_rfm_score(recency, frequency, monetary):\n    r_score = 5 - min(recency // 30, 4)\n    f_score = min(frequency, 4)\n    m_score = min(monetary // 500, 4)\n    return r_score * 100 + f_score * 10 + m_score",
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}

Campos da Resposta:
- source_type: Tipo de origem (computed, external, manual)
- source_location: Localização da origem (ex: feature_service, database, api)
- dependencies: Lista de features que esta feature depende
- computation_script: Script ou lógica de computação

Erros:
- 404: Lineage não encontrado

6.2 Criar/Atualizar Lineage

Endpoint: POST /lineage

Descrição: Cria ou atualiza lineage de uma feature.

Parâmetros de Query:
- feature_name (string, obrigatório) - Nome da feature
- source_type (string, obrigatório) - Tipo de origem (computed, external, manual)
- source_location (string, opcional) - Localização da origem
- dependencies (array, opcional) - Lista de dependências
- computation_script (string, opcional) - Script de computação

Exemplo:

curl -X POST "https://csuite.internut.com.br/feature-store/lineage?feature_name=rfm_score&source_type=computed&source_location=feature_store&dependencies=recency_days&dependencies=freq_90d&dependencies=value_90d" \
  -H "Content-Type: application/json" \
  -d '{
    "computation_script": "def compute_rfm_score(recency, frequency, monetary):\n    return (recency, frequency, monetary)"
  }'

Resposta:

{
  "id": 1,
  "feature_name": "rfm_score",
  "source_type": "computed",
  "source_location": "feature_store",
  "dependencies": ["recency_days", "freq_90d", "value_90d"],
  "computation_script": "def compute_rfm_score(recency, frequency, monetary):\n    return (recency, frequency, monetary)",
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:05:00Z"
}

Comportamento:
- Se lineage existe, atualiza
- Se não existe, cria novo

6.3 Obter Dependências (Recursivo)

Endpoint: GET /lineage/{feature_name}/dependencies

Descrição: Obtém todas as dependências de uma feature (recursivo).

Parâmetros de Path:
- feature_name (string, obrigatório) - Nome da feature

Exemplo:

curl "https://csuite.internut.com.br/feature-store/lineage/rfm_score/dependencies"

Resposta:

{
  "feature": "rfm_score",
  "direct_dependencies": ["recency_days", "freq_90d", "value_90d"],
  "all_dependencies": [
    "recency_days",
    "freq_90d",
    "value_90d",
    "last_purchase_date",
    "order_count_90d",
    "order_total_90d"
  ]
}

Campos da Resposta:
- feature: Nome da feature
- direct_dependencies: Dependências diretas
- all_dependencies: Todas as dependências (incluindo transitivas)

Casos de Uso:
- Validar dependências antes de deletar feature
- Entender impacto de mudanças
- Visualizar árvore de dependências

7. Sync API

Base Path: /sync-definitions

7.1 Sincronizar Definições

Endpoint: POST /sync-definitions

Descrição: Sincroniza definições de features do Feature Service existente (4C).

Exemplo:

curl -X POST "https://csuite.internut.com.br/feature-store/sync-definitions"

Resposta:

{
  "status": "success",
  "synced_count": 15,
  "message": "15 definições sincronizadas"
}

Comportamento:
- Busca definições do Feature Service (4C)
- Cria ou atualiza definições no Feature Store
- Retorna número de definições sincronizadas

Casos de Uso:
- Sincronização inicial
- Atualização periódica (via cron)
- Migração de features

8. Exemplos Práticos

8.1 Fluxo Completo: Definir → Computar → Obter

# 1. Criar definição de feature
curl -X POST "https://csuite.internut.com.br/feature-store/definitions" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "recency_days",
    "description": "Dias desde a última compra",
    "feature_type": "numeric",
    "version": "v1",
    "status": "active"
  }'

# 2. Computar feature para um cliente
curl -X POST "https://csuite.internut.com.br/feature-store/compute" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "customer",
    "entity_id": "12345",
    "feature_names": ["recency_days"],
    "force_recompute": false
  }'

# 3. Obter valores (com cache)
curl -X POST "https://csuite.internut.com.br/feature-store/values" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "customer",
    "entity_id": "12345",
    "feature_names": ["recency_days"],
    "use_cache": true
  }'

8.2 Criar Grupo RFM e Obter Features

# 1. Criar grupo RFM
curl -X POST "https://csuite.internut.com.br/feature-store/groups?name=rfm_features&description=Features RFM&category=rfm&features=recency_days&features=freq_90d&features=value_90d"

# 2. Obter todas as features de um cliente
curl -X POST "https://csuite.internut.com.br/feature-store/values" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "customer",
    "entity_id": "12345",
    "use_cache": true
  }'

8.3 Rastrear Dependências

# 1. Criar lineage para feature composta
curl -X POST "https://csuite.internut.com.br/feature-store/lineage?feature_name=rfm_score&source_type=computed&dependencies=recency_days&dependencies=freq_90d&dependencies=value_90d"

# 2. Obter todas as dependências (recursivo)
curl "https://csuite.internut.com.br/feature-store/lineage/rfm_score/dependencies"

# 3. Verificar impacto antes de deletar feature
curl "https://csuite.internut.com.br/feature-store/lineage/recency_days/dependencies"

8.4 Sincronização Automática

# Sincronizar definições do Feature Service
curl -X POST "https://csuite.internut.com.br/feature-store/sync-definitions"

# Verificar definições sincronizadas
curl "https://csuite.internut.com.br/feature-store/definitions?status=active"

9. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-feature-store está rodando
Verifique se o path está correto (/feature-store/definitions, etc.)
Verifique se o endpoint existe na documentação OpenAPI

Erro: "Feature já existe" (400)

Use GET /definitions/{feature_name} para verificar se feature existe
Use PUT /definitions/{feature_name} para atualizar (se disponível)
Verifique se está tentando criar feature duplicada

Erro: "Feature não encontrada" (404)

Verifique se a feature existe: GET /definitions
Verifique se o nome da feature está correto (case-sensitive)
Verifique se a feature está ativa (status=active)

Features não aparecem no cache

Verifique se use_cache=true no request
Verifique se Redis está configurado e acessível
Verifique TTL do cache (FEATURE_CACHE_TTL_SECONDS)
Force recompute: POST /compute com force_recompute=true

Computação lenta

Verifique se feature_names está especificado (evita computar todas)
Verifique se há índices no banco de dados
Verifique logs de computação para identificar features lentas
Considere usar cache para features computadas frequentemente

Sincronização falha

Verifique se FEATURE_SERVICE_URL está configurado
Verifique se o Feature Service (4C) está acessível
Verifique logs do serviço para erros de conexão
Verifique se há features no Feature Service para sincronizar

Dependências não encontradas

Verifique se todas as dependências existem: GET /definitions
Verifique se dependências estão ativas (status=active)
Verifique se há dependências circulares
Use GET /lineage/{feature_name}/dependencies para visualizar árvore

10. Documentação Relacionada

10.1 Documentação Interna

README: csuite-feature-store/README.md
Schema SQL: csuite-feature-store/schema.sql
Integração: docs/operations/INTEGRACAO_FEATURE_STORE.md

10.2 Integrações

Feature Service (4C): Documentação do 4C Feature Service
Scoring Service: Consome features do store
ML Pipeline: Usa features para treinamento

11. Schema do Banco

Tabelas Principais

feature_definitions
- Armazena definições de features
- Campos: id, name, description, feature_type, version, schema, computation_logic, status

feature_values
- Armazena valores computados (com cache)
- Campos: id, entity_type, entity_id, feature_name, value, computed_at, expires_at

feature_groups
- Armazena grupos de features
- Campos: id, name, description, category, features (JSON)

feature_lineage
- Armazena lineage e dependências
- Campos: id, feature_name, source_type, source_location, dependencies (JSON), computation_script

feature_computation_logs
- Armazena logs de computação
- Campos: id, entity_type, entity_id, feature_name, computation_time_ms, status, error, computed_at

Ver csuite-feature-store/schema.sql para detalhes completos.

12. Configuração

Variáveis de Ambiente

# Database
CSUITE_DB_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com
CSUITE_DB_PORT=3306
CSUITE_DB_USER=core
CSUITE_DB_PASSWORD=***
CSUITE_DB_NAME=csuite

# Redis (Cache)
REDIS_HOST=redis
REDIS_PORT=6379
FEATURE_CACHE_TTL_SECONDS=3600

# Feature Service (4C)
FEATURE_SERVICE_URL=http://tasks.4c_feature-service:8081

# Path
ROOT_PATH=/feature-store

13. Próximos Passos

Adicionar versionamento de features ao longo do tempo
Adicionar métricas de qualidade (completeness, freshness, accuracy)
Adicionar suporte a feature transformations (normalização, encoding)
Adicionar exportação de features para formatos ML (Parquet, CSV)
Adicionar monitoramento de uso e performance
Adicionar suporte a feature serving em tempo real

14. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/feature-store/docs

OpenAPI JSON: https://csuite.internut.com.br/feature-store/openapi.json

ReDoc: https://csuite.internut.com.br/feature-store/redoc

Última atualização: 2024-12-20
Versão: 0.1.0

Guia de Uso - APIs /feature-store

📋 Índice

1. Visão Geral

Objetivos

Componentes

Integrações

2. Feature Definitions API

2.1 Listar Definições

2.2 Criar Definição

2.3 Obter Definição

3. Feature Values API

3.1 Obter Valores de Features

4. Feature Compute API

4.1 Computar Features

5. Feature Groups API

5.1 Listar Grupos

5.2 Criar Grupo

5.3 Obter Grupo

6. Feature Lineage API

6.1 Obter Lineage

6.2 Criar/Atualizar Lineage

6.3 Obter Dependências (Recursivo)

7. Sync API

7.1 Sincronizar Definições

8. Exemplos Práticos

8.1 Fluxo Completo: Definir → Computar → Obter

8.2 Criar Grupo RFM e Obter Features

8.3 Rastrear Dependências

8.4 Sincronização Automática

9. Troubleshooting

Erro: "Not Found" (404)

Erro: "Feature já existe" (400)

Erro: "Feature não encontrada" (404)

Features não aparecem no cache

Computação lenta

Sincronização falha

Dependências não encontradas

10. Documentação Relacionada

10.1 Documentação Interna

10.2 Integrações

11. Schema do Banco

Tabelas Principais

12. Configuração

Variáveis de Ambiente

13. Próximos Passos

14. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs `/feature-store`