{"id":26017792,"url":"https://github.com/devbambino/logistik-ai","last_synced_at":"2025-07-31T00:33:23.111Z","repository":{"id":280174047,"uuid":"941159804","full_name":"devbambino/logistik-ai","owner":"devbambino","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-01T18:17:00.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-01T19:22:19.908Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devbambino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-01T16:25:58.000Z","updated_at":"2025-03-01T18:17:03.000Z","dependencies_parsed_at":"2025-03-01T19:22:21.467Z","dependency_job_id":"5ddc3452-fcc9-4774-8a18-3c0e8c93d973","html_url":"https://github.com/devbambino/logistik-ai","commit_stats":null,"previous_names":["devbambino/logistik-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devbambino/logistik-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbambino%2Flogistik-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbambino%2Flogistik-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbambino%2Flogistik-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbambino%2Flogistik-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devbambino","download_url":"https://codeload.github.com/devbambino/logistik-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devbambino%2Flogistik-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267966468,"owners_count":24173549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-03-06T05:30:03.920Z","updated_at":"2025-07-31T00:33:23.074Z","avatar_url":"https://github.com/devbambino.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Logistik AI\n\nAn AI-powered logistics management system that uses Telegram for user interactions. This system helps manage the entire journey of truck drivers, from trip assignment to delivery completion, while keeping all stakeholders (managers, shippers, and consignees) informed.\n\n## Features\n\n- Telegram-based interaction for all users\n- AI agent for natural language processing and decision making\n- Real-time status updates and notifications\n- Location tracking and sharing\n- Issue reporting and resolution\n- Trip management and documentation\n\n## Tech Stack\n\n- **Backend**: Python with FastAPI\n- **AI Framework**: LangChain with Groq SDK (using llama3-70b-8192 model)\n- **Database**: SQLite with SQLAlchemy (can be replaced with PostgreSQL in production)\n- **Messaging**: Telegram Bot API\n- **Development Tools**: Ngrok for webhook development\n\n## System Architecture\n\n### Core Components\n\n1. **FastAPI Application**\n   - RESTful API endpoints for all system operations\n   - Webhook handler for Telegram bot integration\n   - Background task processing\n\n2. **Telegram Bot**\n   - User interface for all stakeholders\n   - Role-based command handling\n   - Interactive buttons and location sharing\n\n3. **AI Agents**\n   - Role-specific AI assistants powered by LangChain and Groq\n   - Natural language understanding and generation\n   - Context-aware responses with conversation memory\n   - Custom agent implementation using LCEL (LangChain Expression Language) pipeline pattern\n   - Direct integration with tools via AgentExecutor rather than binding tools to the LLM\n\n4. **Database Models**\n   - Users (drivers, managers, shippers, consignees)\n   - Trips (assignments, statuses, locations)\n   - Issues (reporting and resolution)\n   - Notifications (messaging between stakeholders)\n\n### User Roles\n\n1. **Driver Agent**\n   - Trip management and status updates\n   - Location sharing\n   - Issue reporting\n   - Communication with other stakeholders\n\n2. **Manager Agent**\n   - Trip monitoring and assignment\n   - Issue resolution\n   - Communication with drivers, shippers, and consignees\n   - Creating new trips\n\n3. **Shipper Agent**\n   - Shipment tracking\n   - Communication with drivers and managers\n   - Issue reporting and monitoring\n\n4. **Consignee Agent**\n   - Incoming shipment tracking\n   - Estimated arrival time monitoring\n   - Communication with drivers and shippers\n\n### Data Flow\n\n1. User sends a message via Telegram\n2. Message is processed by the appropriate agent based on user role\n3. Agent interacts with the database and generates a response\n4. Response is sent back to the user via Telegram\n5. Status updates and notifications are sent to relevant stakeholders\n\n## Setup Instructions\n\n### Prerequisites\n\n- Python 3.9+\n- Telegram account\n- Groq API key\n\n### Installation\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/yourusername/logistik-ai.git\n   cd logistik-ai\n   ```\n\n2. Create a virtual environment:\n   ```\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. Install dependencies:\n   ```\n   pip install -r requirements.txt\n   ```\n\n4. Create a Telegram bot:\n   - Talk to [BotFather](https://t.me/botfather) on Telegram\n   - Use the `/newbot` command to create a new bot\n   - Copy the API token\n\n5. Set up environment variables:\n   - Copy `.env.example` to `.env`\n   - Fill in your Telegram Bot Token and Groq API Key\n\n### Running the Application\n\n1. Initialize the database:\n   ```\n   python create_db.py  # Creates empty database tables\n   ```\n   \n   Or initialize with test data:\n   ```\n   python scripts/init_db.py  # Creates database tables and populates with test data\n   ```\n\n2. Start the application:\n   ```\n   python run.py\n   ```\n   or\n   ```\n   uvicorn app.main:app --reload\n   ```\n\n3. Set up ngrok for webhook (in a separate terminal):\n   ```\n   ngrok http 8000\n   ```\n\n4. Configure the webhook:\n   ```\n   python scripts/setup_ngrok.py\n   ```\n\n## Implementation Notes\n\n### Agent Implementation\n\nThe AI agents in this system are implemented using a custom approach with the Groq LLM model. Since the `bind_tools` method is not implemented for the Groq model in the current version of LangChain, we use a direct approach:\n\n1. We define tools as LangChain Tool objects with their respective functions\n2. We create a ChatPromptTemplate with system message, chat history, user input, and agent scratchpad\n3. We use the LCEL (LangChain Expression Language) pipeline pattern to connect components\n4. Instead of binding tools to the LLM, we pass them directly to the AgentExecutor\n5. The OpenAIFunctionsAgentOutputParser is used to parse the LLM output and extract tool calls\n\nThis approach ensures compatibility with the Groq model while maintaining the agent's ability to use tools effectively.\n\n## Project Structure\n\n```\nlogistik-ai/\n├── app/                      # Main application package\n│   ├── agents/               # AI agents for different user roles\n│   │   ├── __init__.py\n│   │   ├── driver_agent.py\n│   │   ├── manager_agent.py\n│   │   ├── shipper_agent.py\n│   │   └── consignee_agent.py\n│   ├── __init__.py\n│   ├── bot.py                # Telegram bot implementation\n│   ├── database.py           # Database connection and session\n│   ├── main.py               # FastAPI application and endpoints\n│   ├── models.py             # SQLAlchemy database models\n│   ├── schemas.py            # Pydantic schemas for validation\n│   └── utils.py              # Utility functions\n├── scripts/                  # Helper scripts\n│   ├── init_db.py            # Database initialization with test data\n│   └── setup_ngrok.py        # Ngrok webhook configuration\n├── create_db.py              # Database initialization script\n├── .env.example              # Example environment variables\n├── .gitignore                # Git ignore file\n├── README.md                 # Project documentation\n├── requirements.txt          # Python dependencies\n└── run.py                    # Application entry point\n```\n\n## Usage\n\n1. Start a conversation with your bot on Telegram\n2. Select your role (driver, manager, shipper, or consignee)\n3. Follow the prompts to interact with the system\n4. Use the provided buttons for quick responses\n\n### Common Commands\n\n- `/start` - Begin interaction and set your role\n- `/help` - Get role-specific help information\n- `/status` - Check current status (varies by role)\n- `/setrole` - Change your current role\n\n## Hackathon Project\n\nThis project was created for a hackathon and is intended for demonstration purposes. In a production environment, you would want to implement additional security measures, more robust error handling, and potentially replace SQLite with a more scalable database solution like PostgreSQL.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevbambino%2Flogistik-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevbambino%2Flogistik-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevbambino%2Flogistik-ai/lists"}