{"id":31828367,"url":"https://github.com/unclecode/agentloop","last_synced_at":"2025-10-11T19:28:59.667Z","repository":{"id":280959445,"uuid":"943722319","full_name":"unclecode/agentloop","owner":"unclecode","description":"An iterative approach to get every LLM act agentic.","archived":false,"fork":false,"pushed_at":"2025-03-19T11:29:29.000Z","size":627,"stargazers_count":3,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-06T10:57:48.384Z","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/unclecode.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-06T06:51:07.000Z","updated_at":"2025-10-04T15:48:04.000Z","dependencies_parsed_at":"2025-03-06T08:42:58.696Z","dependency_job_id":null,"html_url":"https://github.com/unclecode/agentloop","commit_stats":null,"previous_names":["unclecode/agentloop"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/unclecode/agentloop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclecode%2Fagentloop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclecode%2Fagentloop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclecode%2Fagentloop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclecode%2Fagentloop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unclecode","download_url":"https://codeload.github.com/unclecode/agentloop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclecode%2Fagentloop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279008424,"owners_count":26084460,"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-10-11T02:00:06.511Z","response_time":55,"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-10-11T19:28:48.438Z","updated_at":"2025-10-11T19:28:59.654Z","avatar_url":"https://github.com/unclecode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentloop\n\nA lightweight, transparent, and highly customizable Python library for building AI assistants using OpenAI's Chat Completions API. With a core implementation under 200 lines, it balances simplicity with power, enabling developers to build assistants that manage long conversations, execute multiple tasks, and maintain context across sessions—all while offering full control over data and behavior.\n\n## Key Features\n\n- **Assistant Creation**: Define assistants with models, system messages, tools, templates, and guardrails.\n- **Session Management**: Persistent, locally stored sessions with SQLite for seamless conversation continuity.\n- **Memory System**: Integration with `Mem4ai` for storing and retrieving contextual data.\n- **Message Processing**: Handle user inputs, tool execution loops, and structured outputs with ease.\n- **Transparency**: Inspect and modify conversation history, memory, and session data directly.\n- **Flexibility**: Supports vision, token tracking, and dynamic templates for tailored interactions.\n\n## Installation\n\nFirst, clone the repository:\n```bash\ngit clone https://github.com/MojitoFilms/agentloop.git\ncd agentloop\n```\n\nThen install the dependencies:\n```bash\n# Install from requirements.txt\npip install -r requirements.txt\n\n# Or install directly\npip install openai tiktoken\npip install git+https://github.com/unclecode/mem4ai.git\n```\n\nSet your OpenAI API key:\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n## Quick Start\n\nCreate a simple assistant and start a conversation:\n\n```python\nfrom agentloop import agentloop\n\n# Define a tool\ndef get_weather(city: str) -\u003e str:\n    \"\"\"Return the weather for a given city.\"\"\"\n    return f\"Weather in {city}: Sunny, 20°C\"\n\n# Create assistant\nassistant = agentloop.create_assistant(\n    model_id=\"gpt-4o\",\n    template=\"Hello, {{name}}! I'm your {{role}} assistant.\",\n    template_params={\"name\": \"Alice\", \"role\": \"travel\"},\n    tools=[get_weather],\n    guardrail=\"Don't discuss politics.\",\n    synthesizer_model_id=\"gpt-3.5-turbo\"  # Optional: use a different model for tool calls\n)\n\n# Start session\nsession = agentloop.start_session(assistant, \"user123\")\n\n# Process a message\nresponse = agentloop.process_message(\n    session,\n    \"What's the weather in Paris?\"\n)\n\nprint(response[\"response\"])  # Weather in Paris: Sunny, 20°C\n```\n\n## Core Functions\n\n### Creating an Assistant\n\n```python\nassistant = agentloop.create_assistant(\n    model_id=\"gpt-4o\",\n    system_message=\"You are a helpful assistant.\",\n    tools=[get_weather, book_flight],\n    params={\"temperature\": 0.7},\n    template=\"Hello {{name}}! I am your {{role}} assistant.\",\n    template_params={\"name\": \"User\", \"role\": \"travel\"},\n    guardrail=\"Always be polite and helpful.\",\n    synthesizer_model_id=\"gpt-3.5-turbo\"  # Optional: different model for tool call processing\n)\n```\n\n### Managing Sessions\n\n```python\n# Start a new session or load existing one\nsession = agentloop.start_session(assistant, \"user123\")\n\n# Get or set conversation history\nhistory = agentloop.get_history(session)\nagentloop.set_history(session, new_history)\nagentloop.add_messages(session, [{\"role\": \"user\", \"content\": \"Hello\"}])\n```\n\n### Processing Messages\n\n```python\n# Simple text message\nresponse = agentloop.process_message(\n    session,\n    \"What's the weather in Paris?\"\n)\n\n# With template\nresponse = agentloop.process_message(\n    session,\n    \"What's the weather?\",\n    user_template=\"Query from {{name}}: {{message}}\",\n    template_params={\"name\": \"Alice\"}\n)\n\n# With structured output\nschema = {\n    \"name\": \"weather_response\",\n    \"schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n            \"city\": {\"type\": \"string\"},\n            \"temperature\": {\"type\": \"string\"},\n            \"conditions\": {\"type\": \"string\"}\n        },\n        \"required\": [\"city\", \"temperature\", \"conditions\"],\n        \"additionalProperties\": False\n    },\n    \"strict\": True\n}\n\nresponse = agentloop.process_message(\n    session,\n    \"What's the weather in Paris?\",\n    schema=schema\n)\n```\n\n### Working with Memory\n\nAgentloop uses [Mem4ai](https://github.com/unclecode/mem4ai) for memory management:\n\n```python\n# Add a memory\nagentloop.update_memory(\n    session,\n    \"User prefers metric units\",\n    {\"type\": \"preference\", \"value\": \"metric\"}\n)\n\n# Get memory instance\nmemtor = agentloop.get_memory(session)\n```\n\n## Running the Example\n\nTry the included example:\n\n```bash\n# Make sure you're in the agentloop directory\npython example.py\n```\n\n## Use Cases\n\n- **Travel Planners**: Search flights, recommend destinations, and remember user preferences.\n- **Customer Support**: Handle inquiries, search knowledge bases, and maintain conversation context.\n- **Research Assistants**: Extract information from documents, organize findings, and generate summaries.\n- **Creative Writing Aids**: Brainstorm ideas, suggest improvements, and provide feedback on drafts.\n\n## Data Storage\n\nAll session data is stored locally in SQLite at `~/.agentloop/agentloop.db`, giving you full control over your data.\n\n## License\n\nMIT License","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funclecode%2Fagentloop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funclecode%2Fagentloop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funclecode%2Fagentloop/lists"}