{"id":31681344,"url":"https://github.com/romanslack/simuverse_framework_mk3","last_synced_at":"2025-10-08T07:48:23.269Z","repository":{"id":289316747,"uuid":"970854598","full_name":"RomanSlack/SimuVerse_Framework_MK3","owner":"RomanSlack","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-22T17:13:17.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T17:48:45.649Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RomanSlack.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}},"created_at":"2025-04-22T16:28:26.000Z","updated_at":"2025-04-22T17:13:20.000Z","dependencies_parsed_at":"2025-04-22T17:58:55.740Z","dependency_job_id":null,"html_url":"https://github.com/RomanSlack/SimuVerse_Framework_MK3","commit_stats":null,"previous_names":["romanslack/simuverse_framework_mk3"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RomanSlack/SimuVerse_Framework_MK3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FSimuVerse_Framework_MK3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FSimuVerse_Framework_MK3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FSimuVerse_Framework_MK3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FSimuVerse_Framework_MK3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RomanSlack","download_url":"https://codeload.github.com/RomanSlack/SimuVerse_Framework_MK3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RomanSlack%2FSimuVerse_Framework_MK3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278909712,"owners_count":26066887,"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-08T02:00:06.501Z","response_time":56,"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-08T07:48:02.852Z","updated_at":"2025-10-08T07:48:23.262Z","avatar_url":"https://github.com/RomanSlack.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimuVerse Backend\n\nThis is the Python backend for the SimuVerse agent simulation system that handles agent decision making using OpenAI's GPT models.\n\n## Setup\n\n1. Install the required dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n2. Create a `.env` file in this directory with your OpenAI API key:\n   ```\n   OPENAI_API_KEY=your_api_key_here\n   ```\n\n3. Run the server:\n   ```bash\n   python main.py\n   ```\n\n## Agent Profiles\n\nAgent profiles are stored in `agent_profiles.json`. Each agent has the following configurable properties:\n\n- `personality`: Defines the agent's personality traits and characteristics\n- `task`: The current task or objective for the agent\n- `default_location`: The default starting location (e.g., \"park\", \"library\")\n\nExample:\n```json\n{\n  \"Agent_A\": {\n    \"personality\": \"Curious and analytical. You are a Mars colony scientist specializing in environmental systems.\",\n    \"task\": \"Explore the colony and report any findings about the environment.\",\n    \"default_location\": \"park\"\n  }\n}\n```\n\n## API Endpoints\n\n### Agent Management\n\n- `GET /health`: Health check endpoint\n- `POST /agent/register`: Register a new agent\n- `DELETE /agent/{agent_id}`: Delete an agent\n- `POST /generate`: Generate agent decision using LLM\n- `POST /env/update`: Update environment state\n- `GET /env/{agent_id}`: Get environment state for a specific agent\n\n### Agent Profiles\n\n- `GET /profiles`: List all agent profiles\n- `GET /profiles/{agent_id}`: Get a specific agent's profile\n- `POST /profiles/{agent_id}`: Update an agent's profile\n- `DELETE /profiles/{agent_id}`: Delete an agent's profile\n\nExample profile update:\n```bash\ncurl -X POST http://localhost:3000/profiles/Agent_A \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"personality\": \"Curious and analytical\", \"task\": \"Explore the park\"}'\n```\n\n### Logs\n\n- `POST /logs/export`: Export all logs\n- `GET /logs/agent/{agent_id}`: Get logs for a specific agent\n- `GET /logs/agents`: List all agents with logs\n\n### Memory System (New!)\n\nThe backend includes a vector-based memory system that allows agents to recall past experiences:\n\n- `POST /memory/{agent_id}`: Store a new memory for an agent\n- `POST /memory/{agent_id}/query`: Query an agent's memories\n- `GET /memory/{agent_id}`: Get all memories for an agent\n- `GET /memory/{agent_id}/{memory_id}`: Get a specific memory\n- `DELETE /memory/{agent_id}/{memory_id}`: Delete a specific memory\n- `DELETE /memory/{agent_id}`: Clear all memories for an agent\n- `GET /memory/`: List all agents with memories\n\nTo enable the memory system:\n\n```bash\n# Setup the memory system\n./setup_memory_system.sh\n\n# Start the system with Docker support for vector database\ndocker-compose -f docker-compose.memory.yml up -d\n```\n\nFor more details, see [Memory System README](memory_system/README.md).\n\n## Environment State\n\nThe system maintains an environment state that includes:\n\n- Agent positions and statuses\n- Nearby agents for each agent\n- Nearby objects for each agent\n- Location information\n\nThis state is updated regularly from the Unity frontend and used to provide context to the LLM for making decisions.\n\n## Unity Integration\n\nThe backend communicates with the Unity frontend through HTTP APIs:\n\n- Unity sends environment updates to the backend\n- The backend sends action commands back to Unity\n- All communication uses JSON format\n\n## Debugging\n\nCheck the `agent_logs` directory for detailed logs of agent interactions with the LLM system. Each agent has its own log file tracking:\n\n1. Prompts sent to the LLM\n2. Responses received\n3. Parsed actions\n4. Timestamps for each interaction\n\n## Features\n\n### Agent Communication\nAgents can communicate with each other through the `SPEAK` action when they are at the same location. Messages are delivered to all agents at the same location.\n\n### Memory System\nAgents have a semantic memory system that allows them to:\n- Remember past interactions and experiences\n- Retrieve relevant memories based on their current context\n- Have a continuity of experience as they navigate the simulation\n\n### Agent Dashboard\nA web-based dashboard is available for monitoring agent status and interactions at http://localhost:5001 when the backend is running.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromanslack%2Fsimuverse_framework_mk3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromanslack%2Fsimuverse_framework_mk3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromanslack%2Fsimuverse_framework_mk3/lists"}