Car Agent Python

Seções do projeto

• Descrição
• Funcionalidades
• Tecnologias
• Instalação e Execução
• API
• Agente de IA

✔️ Descrição

Car Agent Python é uma aplicação web inteligente que utiliza Inteligência Artificial para auxiliar na busca e venda de carros. O sistema conta com um agente conversacional avançado que entende pedidos em linguagem natural e busca veículos no estoque com base nos critérios especificados pelo cliente.

O projeto implementa uma arquitetura limpa (Clean Architecture) com Django REST Framework + Domain Driven Design, integrando tecnologias de IA como LangChain, OpenAI GPT-4 e MCP (Model Context Protocol) para criar uma experiência de venda personalizada e eficiente.

💻 Funcionalidades

🔍 Busca Inteligente de Carros

• Busca por filtros específicos: marca, modelo, cor, ano, preço, combustível, transmissão, quilometragem
• Busca em linguagem natural: "Quero um HB20 preto" ou "Carros Toyota até 70 mil reais"
• Filtros combinados: múltiplos critérios de busca simultâneos
• Resultados paginados: otimização para grandes volumes de dados

🤖 Agente Conversacional de IA

• Compreensão de linguagem natural: interpreta pedidos complexos do cliente
• Respostas personalizadas: responde como um vendedor experiente
• Contexto de conversa: mantém histórico da conversa
• Recomendações inteligentes: destaca os melhores veículos encontrados

📊 Gestão de Dados

• Banco de dados PostgreSQL: armazenamento robusto e escalável
• Seeds automáticos: população inicial do banco com dados de exemplo
• API RESTful: endpoints padronizados para integração
• Validação de dados: garantia de integridade das informações

🐳 Containerização

• Docker: ambiente de desenvolvimento isolado
• Docker Compose: orquestração de serviços (aplicação + banco)
• Configuração simplificada: setup rápido e reproduzível

🔨 Tecnologias

Backend

• Python 3.12
• Django 5.2.7
• Django REST Framework 3.16.1
• PostgreSQL
• SQLAlchemy 2.0.44

Inteligência Artificial

• LangChain 0.3.27
• OpenAI GPT-4
• LangGraph 0.6.10
• MCP (Model Context Protocol)

Desenvolvimento e Testes

• pytest 8.4.2
• pytest-django 4.11.1
• factory-boy 3.3.3
• coverage 7.10.7

Infraestrutura

• Docker
• Docker Compose
• uvicorn 0.37.0
• python-decouple 3.8

🚀 Instalação e Execução

Pré-requisitos

• Docker e Docker Compose instalados
• Chave da API OpenAI configurada

Execução com Docker (Recomendado)

1. Clone o repositório:

git clone <url-do-repositorio>
cd car_agent_python

2. Configure as variáveis de ambiente:

cp .env.example .env
# Edite o arquivo .env com suas configurações

Variáveis de Ambiente Necessárias

OPENAI_API_KEY=sua_chave_openai

SMITHERY_API_KEY=sua_chave_smithery

POSTGRES_USER=usuario_db
POSTGRES_PASSWORD=senha_db
POSTGRES_DB=nome_db

• Para pegar as chaves de api do smithery acesse o site.
• Click na foto de perfil e vai aparecer a opção de API Keys, agora é só criar sua própria API key.

3. Execute com Docker Compose:

  docker compose up -d --build

4. Acesse a aplicação:

  docker exec -it django-app bash

Execução Local (Desenvolvimento)

1. Execute as migrações:

  python manage.py migrate

2. Popule o banco com dados de exemplo:

  python -m src.infrastructure.seeds.seed_cars

3. Execute o agente:

  python -m src.infrastructure.services.langchain_services

💻 API

Endpoints Disponíveis

Método	Endpoint	Descrição	Parâmetros
GET	/cars/	Lista todos os carros	Query parameters para filtros

Filtros de Busca

Parâmetro	Tipo	Descrição	Exemplo
brand	string	Marca do veículo	Toyota
model	string	Modelo do veículo	HB20
color	string	Cor do veículo	preto
year_min	integer	Ano mínimo	2020
year_max	integer	Ano máximo	2023
price_min	float	Preço mínimo	50000
price_max	float	Preço máximo	80000
fuel_type	string	Tipo de combustível	gasolina
transmission	string	Tipo de transmissão	automatico
mileage_max	integer	Quilometragem máxima	50000

Exemplos de Uso

Buscar todos os carros

GET http://localhost:8000/cars/

Buscar carros Toyota com preço entre 60k e 70k

GET http://localhost:8000/cars/?brand=Toyota&price_min=60000&price_max=70000

Buscar HB20 preto

GET http://localhost:8000/cars/?model=HB20&color=preto

Resposta da API

{
  "success": true,
  "count": 3,
  "filters_applied": "{'brand': 'Toyota', 'price_min': 60000, 'price_max': 70000}",
  "data": [
    {
      "brand": "Toyota",
      "model": "Corolla",
      "year": 2021,
      "engine": "2.0",
      "fuel_type": "gasolina",
      "color": "branco",
      "mileage": 25000,
      "doors": 4,
      "transmission": "automatico",
      "price": 65000.0
    }
  ]
}

🤖 Agente de IA

Funcionalidades do Agente

O agente conversacional utiliza tecnologias avançadas de IA para:

1. Interpretação de Linguagem Natural: Converte pedidos do cliente em filtros estruturados
2. Busca Inteligente: Utiliza os filtros extraídos para buscar veículos no estoque
3. Resposta Contextual: Fornece respostas naturais e úteis como um vendedor experiente
4. Memória de Conversa: Mantém contexto entre as interações

Exemplos de Interação

Cliente: "Quero um HB20 preto" Agente: "Encontrei 2 carros HB20 pretos disponíveis! Vou te mostrar os detalhes..."

Cliente: "Carros Toyota até 70 mil reais" Agente: "Encontrei 5 carros Toyota dentro do seu orçamento! Aqui estão as melhores opções..."

🧪 Testes

Execute os testes com:

 python3 run_tests.py --all

📁 Estrutura do Projeto

car_agent_python/
├── src/
│   ├── application/          # Casos de uso
│   ├── domain/              # Entidades e regras de negócio
│   ├── infrastructure/      # Implementações técnicas
│   │   ├── prompts/         # Prompts do agente IA
│   │   ├── services/        # Serviços (LangChain, MCP)
│   │   └── seeds/           # Dados de exemplo
│   └── web/                 # Controllers e serializers
├── tests/                   # Testes unitários e integração
├── docker-compose.yaml      # Configuração Docker
├── Dockerfile              # Imagem Docker
└── requirements.txt        # Dependências Python