{"id":35323989,"url":"https://github.com/benorbiato/llm-engine","last_synced_at":"2026-04-11T09:02:08.140Z","repository":{"id":326132544,"uuid":"1100638647","full_name":"benorbiato/llm-engine","owner":"benorbiato","description":"Automated judicial process verification system powered by LLM technology for intelligent decision-making based on company business policies.","archived":false,"fork":false,"pushed_at":"2025-11-26T03:38:16.000Z","size":347,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T01:19:39.682Z","etag":null,"topics":["docker","fastapi","llm","python","streamlit"],"latest_commit_sha":null,"homepage":"https://llm-engine.onrender.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benorbiato.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T14:53:03.000Z","updated_at":"2025-11-26T03:38:19.000Z","dependencies_parsed_at":"2025-11-30T13:05:21.921Z","dependency_job_id":null,"html_url":"https://github.com/benorbiato/llm-engine","commit_stats":null,"previous_names":["benorbiato/llm-engine"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/benorbiato/llm-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benorbiato%2Fllm-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benorbiato%2Fllm-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benorbiato%2Fllm-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benorbiato%2Fllm-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benorbiato","download_url":"https://codeload.github.com/benorbiato/llm-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benorbiato%2Fllm-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31674624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T08:18:19.405Z","status":"ssl_error","status_checked_at":"2026-04-11T08:17:08.892Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","llm","python","streamlit"],"created_at":"2025-12-31T00:58:28.385Z","updated_at":"2026-04-11T09:02:08.134Z","avatar_url":"https://github.com/benorbiato.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# LLM Verification Engine\n\nAutomated judicial process verification system powered by LLM technology for intelligent decision-making based on company business policies.\n\n**Live Deployment:** https://llm-engine.onrender.com\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Running the Application](#running-the-application)\n- [API Endpoints](#api-endpoints)\n- [Configuration](#configuration)\n- [Docker Deployment](#docker-deployment)\n- [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThis application automates the verification and eligibility assessment of judicial processes against predefined business policies. The system leverages LLM technology through Groq API to provide intelligent analysis and transparent decision-making.\n\n### Key Features\n\n- Automated process analysis and verification\n- Structured decision outcomes: approved, rejected, or incomplete\n- Policy-driven verification with clear justifications\n- Batch processing for multiple processes simultaneously\n- Caching mechanism to optimize API usage\n- Comprehensive analytics and monitoring\n- RESTful API with automatic documentation\n- Streamlit web interface for user interaction\n\n### Architecture\n\n```\napp/\n├── api/                    # API routes and middleware\n│   ├── middleware/         # Logging and error handling\n│   └── routes/            # Endpoint definitions\n├── config.py              # Configuration management\n├── domain/                # Business logic and policies\n├── external/              # External service integrations\n├── repositories/          # Data persistence\n├── schemas/               # Request/response models\n├── use_cases/             # Business use case implementations\n└── utils/                 # Utilities (logging, caching)\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.11 or higher\n- Groq API key (obtain at https://console.groq.com/)\n- Docker and Docker Compose (optional, for containerized deployment)\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd llm-engine\n```\n\n2. Create and activate virtual environment:\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n4. Configure environment variables:\n```bash\ncp .env.example .env\n# Edit .env and add your GROQ_API_KEY\n```\n\n### Environment Variables\n\nCreate a `.env` file in the project root:\n\n```\nGROQ_API_KEY=your_groq_api_key_here\nGROQ_MODEL=mixtral-8x7b-32768\nMAX_TOKENS=2048\nTEMPERATURE=0.3\nLOG_LEVEL=INFO\nENVIRONMENT=development\nDEBUG=False\nHOST=0.0.0.0\nPORT=8000\n```\n\n## Running the Application\n\n### API Only\n\n```bash\npython app/main.py\n```\n\nThe API will be available at `http://localhost:8000`\n\nAccess API documentation:\n- Swagger UI: http://localhost:8000/docs\n- ReDoc: http://localhost:8000/redoc\n\n### Using Docker Compose\n\n```bash\ndocker-compose up\n```\n\nServices will be available at:\n- API: http://localhost:8000\n- UI (Streamlit): http://localhost:8501\n\n### Stopping the Application\n\n```bash\ndocker-compose down\n```\n\n## API Endpoints\n\n### Health \u0026 Monitoring\n\n#### GET `/health`\nCheck application health status.\n\n**Response:**\n```json\n{\n  \"status\": \"healthy\",\n  \"timestamp\": \"2024-11-26T10:30:00.000000\",\n  \"version\": \"1.0.0\"\n}\n```\n\n#### GET `/monitoring/api-status`\nGet API configuration and service status.\n\n**Response:**\n```json\n{\n  \"status\": \"operational\",\n  \"api\": {\n    \"provider\": \"Groq\",\n    \"model\": \"mixtral-8x7b-32768\",\n    \"api_key_configured\": true,\n    \"max_tokens_per_request\": 2048\n  },\n  \"cache\": {\n    \"total_entries\": 125,\n    \"cache_hits\": 450,\n    \"cache_misses\": 50\n  }\n}\n```\n\n#### GET `/monitoring/cache-stats`\nGet cache performance statistics.\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"cache\": {\n    \"total_entries\": 125,\n    \"cache_hits\": 450,\n    \"cache_misses\": 50\n  }\n}\n```\n\n#### POST `/monitoring/cache/clear`\nClear all cached verification results.\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Cache cleared successfully\"\n}\n```\n\n### Verification Endpoints\n\n#### POST `/verify/`\nVerify a single judicial process.\n\n**Request Body:**\n```json\n{\n  \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n  \"classe\": \"Cumprimento de Sentença contra a Fazenda Pública\",\n  \"orgaoJulgador\": \"19ª VARA FEDERAL - SOBRAL/CE\",\n  \"ultimaDistribuicao\": \"2024-11-18T23:15:44.130Z\",\n  \"assunto\": \"Rural (Art. 48/51)\",\n  \"segredoJustica\": false,\n  \"justicaGratuita\": true,\n  \"siglaTribunal\": \"TRF5\",\n  \"esfera\": \"Federal\",\n  \"valorCondenacao\": 67592,\n  \"documentos\": [\n    {\n      \"id\": \"DOC-1-1\",\n      \"dataHoraJuntada\": \"2023-09-10T10:12:05.000\",\n      \"nome\": \"Sentença de Mérito\",\n      \"texto\": \"PODER JUDICIÁRIO...\"\n    }\n  ],\n  \"movimentos\": [\n    {\n      \"dataHora\": \"2024-01-20T11:22:33.000\",\n      \"descricao\": \"Iniciado cumprimento definitivo de sentença.\"\n    }\n  ],\n  \"honorarios\": {\n    \"contratuais\": 6000,\n    \"periciais\": 1200,\n    \"sucumbenciais\": 3000\n  }\n}\n```\n\n**Response (200 OK):**\n```json\n{\n  \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n  \"decision\": \"approved\",\n  \"rationale\": \"Process meets all eligibility criteria and is approved for acquisition.\",\n  \"citations\": [\n    {\n      \"policy_id\": \"POL-1\",\n      \"explanation\": \"Process is in final judgment and execution phase\"\n    },\n    {\n      \"policy_id\": \"POL-2\",\n      \"explanation\": \"Condemnation value is informed: R$ 67,592.00\"\n    }\n  ],\n  \"confidence\": 0.95,\n  \"processingTimeMs\": 234,\n  \"processedAt\": \"2024-11-26T10:30:00.000000\"\n}\n```\n\n#### POST `/verify/batch`\nVerify multiple processes in a single batch request (up to 50 processes).\n\n**Request Body:**\n```json\n{\n  \"processos\": [\n    {\n      \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n      ...\n    },\n    {\n      \"numeroProcesso\": \"0001235-56.2023.4.05.8100\",\n      ...\n    }\n  ]\n}\n```\n\n**Response:**\n```json\n{\n  \"batch_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"total\": 2,\n  \"processados\": 2,\n  \"erros\": 0,\n  \"tempo_total_ms\": 450,\n  \"resultados\": [\n    {\n      \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n      \"decision\": \"approved\",\n      \"rationale\": \"...\",\n      \"citations\": [...],\n      \"confidence\": 0.95\n    },\n    {\n      \"numeroProcesso\": \"0001235-56.2023.4.05.8100\",\n      \"decision\": \"rejected\",\n      \"rationale\": \"...\",\n      \"citations\": [...]\n    }\n  ]\n}\n```\n\n### Process History\n\n#### GET `/process/{numero_processo}`\nRetrieve verification history for a specific process.\n\n**Response:**\n```json\n{\n  \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n  \"ultimaVerificacao\": \"2024-11-26T10:30:00.000000\",\n  \"verificacoes\": 1,\n  \"ultimaDecisao\": \"approved\",\n  \"historico\": [\n    {\n      \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n      \"decision\": \"approved\",\n      \"rationale\": \"...\",\n      \"citations\": [...]\n    }\n  ]\n}\n```\n\n#### GET `/process/`\nList all verified processes with optional filtering.\n\n**Query Parameters:**\n- `decision` (optional): Filter by decision type (approved, rejected, incomplete)\n- `limit` (default: 100): Maximum number of results (1-1000)\n- `offset` (default: 0): Number of items to skip for pagination\n\n**Response:**\n```json\n[\n  {\n    \"numeroProcesso\": \"0001234-56.2023.4.05.8100\",\n    \"decision\": \"approved\",\n    \"rationale\": \"...\",\n    \"citations\": [...],\n    \"confidence\": 0.95,\n    \"processingTimeMs\": 234,\n    \"processedAt\": \"2024-11-26T10:30:00.000000\"\n  }\n]\n```\n\n### Analytics\n\n#### GET `/analytics/summary`\nGet comprehensive analytics summary of all verifications.\n\n**Response:**\n```json\n{\n  \"total_verificacoes\": 150,\n  \"aprovados\": 95,\n  \"rejeitados\": 40,\n  \"incompletos\": 15,\n  \"taxa_aprovacao_percentual\": 63.33,\n  \"taxa_rejeicao_percentual\": 26.67,\n  \"tempo_medio_processamento_ms\": 245.50,\n  \"politicas_mais_citadas\": [\n    {\n      \"id\": \"POL-1\",\n      \"titulo\": \"Final Judgment Status\",\n      \"usos\": 148\n    }\n  ],\n  \"timestamp\": \"2024-11-26T10:30:00.000000\"\n}\n```\n\n#### GET `/analytics/policies-usage`\nGet usage statistics for each policy.\n\n**Response:**\n```json\n{\n  \"POL-1\": 148,\n  \"POL-2\": 145,\n  \"POL-3\": 89,\n  \"POL-4\": 78,\n  \"POL-5\": 23\n}\n```\n\n#### GET `/analytics/decision-distribution`\nGet distribution of decisions across all verifications.\n\n**Response:**\n```json\n{\n  \"approved\": 95,\n  \"rejected\": 40,\n  \"incomplete\": 15,\n  \"total\": 150\n}\n```\n\n#### GET `/analytics/processing-time`\nGet processing time statistics.\n\n**Response:**\n```json\n{\n  \"media_ms\": 245.50,\n  \"minimo_ms\": 120,\n  \"maximo_ms\": 1200,\n  \"total_processamentos\": 150\n}\n```\n\n#### GET `/analytics/top-policies`\nGet the most impactful policies.\n\n**Query Parameters:**\n- `limit` (default: 5): Number of policies to return (1-20)\n\n**Response:**\n```json\n[\n  {\n    \"id\": \"POL-1\",\n    \"titulo\": \"Final Judgment Status\",\n    \"categoria\": \"Process Status\",\n    \"descricao\": \"Process must be in final judgment (transitado em julgado) phase\",\n    \"usos\": 148\n  },\n  {\n    \"id\": \"POL-2\",\n    \"titulo\": \"Condemnation Value Required\",\n    \"categoria\": \"Financial\",\n    \"descricao\": \"Condemnation value must be informed\",\n    \"usos\": 145\n  }\n]\n```\n\n#### GET `/analytics/decision-by-sphere`\nGet decision distribution by judicial sphere (Federal, State, Labor).\n\n**Response:**\n```json\n{\n  \"Federal\": {\n    \"approved\": 80,\n    \"rejected\": 30,\n    \"incomplete\": 10\n  },\n  \"Estadual\": {\n    \"approved\": 10,\n    \"rejected\": 8,\n    \"incomplete\": 3\n  },\n  \"Trabalhista\": {\n    \"approved\": 5,\n    \"rejected\": 2,\n    \"incomplete\": 2\n  }\n}\n```\n\n## Configuration\n\n### Groq API Setup\n\n1. Create an account at https://console.groq.com/\n2. Generate an API key\n3. Add to `.env` file as `GROQ_API_KEY`\n4. Monitor usage in the Groq console\n\n### Logging\n\nThe application uses structured JSON logging. Logs are output to console and can be configured via the `LOG_LEVEL` environment variable:\n- DEBUG: Verbose information\n- INFO: General informational messages\n- WARNING: Warning messages\n- ERROR: Error messages\n\n## Docker Deployment\n\n### Build Image\n\n```bash\ndocker build -t llm-engine:latest .\n```\n\n### Run with Docker\n\n```bash\ndocker run -p 8000:8000 \\\n  -e GROQ_API_KEY=your_key_here \\\n  -e ENVIRONMENT=production \\\n  llm-engine:latest\n```\n\n### Docker Compose\n\n```bash\n# Start services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f api\n\n# Stop services\ndocker-compose down\n```\n\n## Cloud Deployment\n\n### Render.com\n\n1. Push code to GitHub repository\n2. Create new Web Service on Render\n3. Connect your GitHub repository\n4. Set environment variables:\n   - GROQ_API_KEY\n   - ENVIRONMENT=production\n   - LOG_LEVEL=INFO\n5. Deploy\n\nThe application will be available at your Render service URL.\n\n### Other Platforms (Railway, Heroku, etc.)\n\nSimilar process:\n1. Connect GitHub repository\n2. Set environment variables\n3. Deploy with Dockerfile\n4. Verify health endpoint: `/health`\n\n## Troubleshooting\n\n### API Connection Error\n\n**Problem:** Cannot connect to API\n**Solution:** Ensure the application is running and check if port 8000 is available.\n\n```bash\n# Check if port is in use\nnetstat -tuln | grep 8000\n```\n\n### Missing API Key\n\n**Problem:** \"GROQ_API_KEY not configured\"\n**Solution:** Add your Groq API key to `.env` file and restart the application.\n\n### Port Already in Use\n\n**Problem:** \"Port 8000 is already in use\"\n**Solution:** Use a different port:\n\n```bash\ndocker run -p 8001:8000 \\\n  -e GROQ_API_KEY=your_key_here \\\n  llm-engine:latest\n```\n\n### Cache Issues\n\n**Problem:** Stale results from cache\n**Solution:** Clear cache using the endpoint:\n\n```bash\ncurl -X POST http://localhost:8000/monitoring/cache/clear\n```\n\n### High API Usage\n\n**Problem:** Running out of Groq API credits\n**Solution:**\n1. Monitor usage at https://console.groq.com/\n2. Enable caching to reduce API calls\n3. Check cache statistics: `/monitoring/cache-stats`\n4. Consider increasing refresh credits\n\n## Performance\n\n- Average verification processing time: 200-500ms\n- Cache hit rate: 70-90% for repeated processes\n- Batch processing: 50 processes in 5-10 seconds\n- Concurrent requests: Supported with rate limiting\n\n## Support and Resources\n\n- API Documentation: http://localhost:8000/docs\n- Groq Console: https://console.groq.com/\n- Issues: Create an issue in the GitHub repository\n\n## License\n\nThis project is licensed under the MIT License. See LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenorbiato%2Fllm-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenorbiato%2Fllm-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenorbiato%2Fllm-engine/lists"}