{"id":30071404,"url":"https://github.com/pprunty/magikarp-archived","last_synced_at":"2025-08-08T12:42:42.322Z","repository":{"id":289244295,"uuid":"967440153","full_name":"pprunty/magikarp-archived","owner":"pprunty","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-18T14:21:36.000Z","size":14857,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-30T20:24:05.595Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/pprunty.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-16T13:08:17.000Z","updated_at":"2025-07-30T13:58:26.000Z","dependencies_parsed_at":"2025-04-22T10:05:14.136Z","dependency_job_id":"f05086db-bb24-4044-8a97-ead1333bd125","html_url":"https://github.com/pprunty/magikarp-archived","commit_stats":null,"previous_names":["pprunty/magikarp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pprunty/magikarp-archived","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprunty%2Fmagikarp-archived","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprunty%2Fmagikarp-archived/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprunty%2Fmagikarp-archived/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprunty%2Fmagikarp-archived/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pprunty","download_url":"https://codeload.github.com/pprunty/magikarp-archived/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pprunty%2Fmagikarp-archived/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269423871,"owners_count":24414615,"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-08-08T02:00:09.200Z","response_time":72,"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-08-08T12:42:39.517Z","updated_at":"2025-08-08T12:42:42.294Z","avatar_url":"https://github.com/pprunty.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# magikarp\n\nA flexible plugin-based agentic LLM framework built with Go. Magikarp provides a foundation for building AI-powered agents that can interact with the user using _\"**tools**\"_—custom code which the agent can execute to help them complete their task.\nThese tools form the basis for the plugin system. \n\nA plugin is nothing but a \"tool\", where the tool is a predefined \nblock of code the agent knows how to execute, such as `read_file`, `edit_file`, `execute_command`, `trigger_api`, etc.\n\n![shiny_magikarp.png](assets/shiny_magikarp.png)\n\n## Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n1. **Go 1.21 or later**\n   - Option 1: Download and install from [golang.org](https://golang.org/dl/)\n   - Option 2: Install via Homebrew:\n     ```bash\n     brew install go\n     ```\n   - Verify installation: `go version`\n\n2. **Anthropic API Key** (if using Claude integration)\n   - Sign up for an API key at [Anthropic's website](https://console.anthropic.com/)\n   - Set your API key as an environment variable:\n     ```bash\n     export ANTHROPIC_API_KEY=\"your-api-key-here\"\n     ```\n\n## Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/pprunty/magikarp.git\n   cd magikarp\n   ```\n\n2. Install dependencies and build:\n   ```bash\n   make install\n   make build\n   ```\n\n## Quick Start\n\nRun the agent:\n```bash\nmake run\n```\n\n## Model Selection\n\nmagikarp supports multiple LLM providers and models. When you start the application, you'll be presented with a selection menu to choose your preferred provider and model.\n\n### Available Providers\n\n1. **Auto (Smart Model Selection)**\n   - Automatically selects the best model based on the task\n   - No configuration required\n\n2. **Anthropic (Claude)**\n   - Requires `ANTHROPIC_API_KEY` environment variable\n   - Models:\n     - `claude-3-opus`: Most capable model for highly complex tasks\n     - `claude-3-sonnet`: Balanced model for most tasks\n\n3. **OpenAI**\n   - Requires `OPENAI_API_KEY` environment variable\n   - Models:\n     - `gpt-4`: Most capable model for complex tasks\n     - `gpt-3.5-turbo`: Fast and efficient model for most tasks\n\n4. **Google Gemini**\n   - Requires `GEMINI_API_KEY` environment variable\n   - Models:\n     - `gemini-pro`: Most capable Gemini model\n\n5. **Ollama**\n   - Local model running on your machine\n   - Models:\n     - `llama3.2`: Local Llama 3.2 model\n   - Setup Instructions:\n     1. Install Ollama:\n        - macOS: `brew install ollama`\n        - Linux: `curl -fsSL https://ollama.com/install.sh | sh`\n        - Windows: Download from [Ollama website](https://ollama.com/download)\n     2. Start the Ollama server:\n        ```bash\n        ollama serve\n        ```\n     3. Pull the model you want to use:\n        ```bash\n        ollama pull llama3.2\n        ```\n     4. Verify the model is available:\n        ```bash\n        ollama list\n        ```\n   - Documentation:\n     - [Ollama Documentation](https://github.com/ollama/ollama/blob/main/docs/README.md)\n     - [Available Models](https://github.com/ollama/ollama/blob/main/docs/models.md)\n     - [API Documentation](https://github.com/ollama/ollama/blob/main/docs/api.md)\n\n### Selecting a Model\n\n1. Start the application:\n   ```bash\n   make run\n   ```\n\n2. Use the arrow keys to navigate through the provider list\n   - Press `↑` or `↓` to move between options\n   - Press `←` to go back to previous menu\n   - Press `/` to search\n\n3. After selecting a provider, choose your preferred model\n   - Each model includes a description of its capabilities\n   - The selection menu shows both model name and description\n\n4. For API-based providers (Anthropic, OpenAI, Gemini), ensure you have set the required environment variables before starting the application.\n\n## Tool Configuration\n\nmagikarp uses a `tools.json` file to configure tool behavior and trigger keywords. This file defines how tools are presented to the LLM and when they should be used.\n\n### tools.json Structure\n\n```json\n{\n  \"tools\": [\n    {\n      \"name\": \"tool_name\",\n      \"description\": \"Description of what the tool does\",\n      \"category\": \"Category name (e.g., filesystem, execution, text)\",\n      \"trigger_keywords\": [\"keyword1\", \"keyword2\"],\n      \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"property1\": {\n            \"type\": \"string\",\n            \"description\": \"Description of the property\"\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\n### Configuration Fields\n\n- `name`: The name of the tool (must match the tool's implementation)\n- `description`: A clear description of what the tool does\n- `category`: The category the tool belongs to\n- `trigger_keywords`: Keywords that hint when the tool should be used\n- `input_schema`: JSON schema defining the tool's input parameters\n\n### Example Configuration\n\n```json\n{\n  \"tools\": [\n    {\n      \"name\": \"read_file\",\n      \"description\": \"Read the contents of a file\",\n      \"category\": \"filesystem\",\n      \"trigger_keywords\": [\"read\", \"file\", \"contents\", \"show\"],\n      \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"path\": {\n            \"type\": \"string\",\n            \"description\": \"Path to the file to read\"\n          }\n        }\n      }\n    },\n    {\n      \"name\": \"execute_command\",\n      \"description\": \"Execute a shell command\",\n      \"category\": \"execution\",\n      \"trigger_keywords\": [\"run\", \"execute\", \"command\", \"shell\"],\n      \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"command\": {\n            \"type\": \"string\",\n            \"description\": \"Command to execute\"\n          },\n          \"args\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"string\"\n            },\n            \"description\": \"Command arguments\"\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\n### Using tools.json\n\n1. Create a `tools.json` file in your project root\n2. Define your tools with appropriate trigger keywords\n3. The agent will automatically load this configuration when starting\n4. Tools will be triggered when user input contains any of the defined keywords or the model infers the tool should be used\n\n### Best Practices\n\n- Use clear, descriptive tool names\n- Provide detailed descriptions\n- Choose relevant trigger keywords\n- Keep input schemas simple and well-documented\n- Group related tools in the same category\n- Test trigger keywords to ensure they don't conflict\n\n## Development\n\n### Adding New Plugins\n\nmagikarp's plugin architecture makes it easy to add new capabilities. To create a new plugin:\n\n1. Create a new package in `pkg/plugins/your-plugin-name`\n2. Implement the `Plugin` interface:\n   ```go\n   type Plugin interface {\n       Name() string\n       Description() string\n       Tools() []ToolDefinition\n       Initialize() error\n       Cleanup() error\n   }\n   ```\n\n3. Use the `BasePlugin` for common functionality:\n   ```go\n   type YourPlugin struct {\n       *BasePlugin\n   }\n\n   func New() *YourPlugin {\n       return \u0026YourPlugin{\n           BasePlugin: NewBasePlugin(\"your-plugin\", \"Description of what your plugin does\"),\n       }\n   }\n   ```\n\n4. Add tools in the `Initialize` method:\n   ```go\n   func (p *YourPlugin) Initialize() error {\n       p.AddTool(\"tool_name\", \"Description of the tool\", \n           map[string]interface{}{\n               \"type\": \"object\",\n               \"properties\": {\n                   \"input\": {\n                       \"type\": \"string\",\n                       \"description\": \"Tool input\"\n                   }\n               }\n           },\n           func(input []byte) (string, error) {\n               result := NewToolResult(true, \"Success\", data)\n               return result.ToJSON()\n           })\n       return nil\n   }\n   ```\n\n5. Register your plugin in `main.go`\n\nExample plugin structure:\n```go\npackage yourplugin\n\ntype YourPlugin struct {\n    *BasePlugin\n}\n\nfunc New() *YourPlugin {\n    return \u0026YourPlugin{\n        BasePlugin: NewBasePlugin(\"your-plugin\", \"Description of what your plugin does\"),\n    }\n}\n\nfunc (p *YourPlugin) Initialize() error {\n    p.AddTool(\"example_tool\", \"Example tool description\",\n        map[string]interface{}{\n            \"type\": \"object\",\n            \"properties\": {\n                \"input\": {\n                    \"type\": \"string\",\n                    \"description\": \"Example input\"\n                }\n            }\n        },\n        func(input []byte) (string, error) {\n            var data struct {\n                Input string `json:\"input\"`\n            }\n            if err := json.Unmarshal(input, \u0026data); err != nil {\n                return \"\", err\n            }\n            result := NewToolResult(true, \"Processed successfully\", data.Input)\n            return result.ToJSON()\n        })\n    return nil\n}\n\nfunc (p *YourPlugin) Cleanup() error {\n    return nil\n}\n```\n\n### Tool Definition\n\nEach tool must implement the `ToolDefinition` interface:\n```go\ntype ToolDefinition struct {\n    Name        string                 // Name of the tool\n    Description string                 // Description of what the tool does\n    InputSchema map[string]interface{} // JSON schema for tool input\n    Function    func(input []byte) (string, error) // Tool implementation\n}\n```\n\n### Tool Results\n\nTools should return results using the `ToolResult` struct:\n```go\ntype ToolResult struct {\n    Success bool        // Whether the tool execution was successful\n    Message string      // Status message\n    Data    interface{} // Result data\n}\n```\n\nUse `NewToolResult` to create results and `ToJSON` to convert them to JSON:\n```go\nresult := NewToolResult(true, \"Operation successful\", data)\njsonResult, err := result.ToJSON()\n```\n\n### Available Commands\n\n- `make install` - Install dependencies\n- `make build` - Build the binary\n- `make run` - Build and run the binary\n- `make test` - Run tests\n- `make clean` - Clean build artifacts\n- `make lint` - Run linter\n- `make tools` - Install development tools\n\n## Project Structure\n\n```\nmagikarp/\n├── pkg/\n│   ├── agent/         # Core agent implementation\n│   ├── llm/           # LLM provider implementations\n│   │   ├── anthropic.go  # Anthropic (Claude) client\n│   │   ├── auto.go       # Auto model selection client\n│   │   ├── gemini.go     # Google Gemini client\n│   │   ├── ollama.go     # Ollama local model client\n│   │   └── openai.go     # OpenAI client\n│   ├── plugins/       # Plugin implementations\n│   │   ├── execution/ # Command execution plugin\n│   │   ├── filesystem/# File system operations plugin\n│   │   └── text/      # Text manipulation plugin\n├── main.go           # Entry point\n├── Makefile         # Build and development commands\n└── README.md        # This file\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see LICENSE file for details ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpprunty%2Fmagikarp-archived","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpprunty%2Fmagikarp-archived","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpprunty%2Fmagikarp-archived/lists"}