{"id":30185209,"url":"https://github.com/ccoreilly/agent-softcatala","last_synced_at":"2025-08-12T13:11:03.173Z","repository":{"id":307855815,"uuid":"1030848510","full_name":"ccoreilly/agent-softcatala","owner":"ccoreilly","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-02T17:35:46.000Z","size":30,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T17:36:39.608Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/ccoreilly.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,"zenodo":null}},"created_at":"2025-08-02T13:06:35.000Z","updated_at":"2025-08-02T15:48:15.000Z","dependencies_parsed_at":"2025-08-02T17:36:44.876Z","dependency_job_id":"6b81a365-f040-44ef-ba98-5af2bfa1c238","html_url":"https://github.com/ccoreilly/agent-softcatala","commit_stats":null,"previous_names":["ccoreilly/agent-softcatala"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ccoreilly/agent-softcatala","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccoreilly%2Fagent-softcatala","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccoreilly%2Fagent-softcatala/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccoreilly%2Fagent-softcatala/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccoreilly%2Fagent-softcatala/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccoreilly","download_url":"https://codeload.github.com/ccoreilly/agent-softcatala/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccoreilly%2Fagent-softcatala/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270065450,"owners_count":24520946,"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-12T02:00:09.011Z","response_time":80,"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-12T13:11:02.272Z","updated_at":"2025-08-12T13:11:03.163Z","avatar_url":"https://github.com/ccoreilly.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chat Agent - AI Assistant with Tools\n\nA modern web-based chat application that allows you to interact with AI agents powered by open-source LLMs through Ollama. The agents have access to tools and can perform actions like web browsing.\n\n## Features\n\n- 🤖 **AI Agent Integration**: Powered by Ollama with configurable open-source models\n- 🛠️ **Native Tool Support**: Uses Ollama's built-in tool calling API for reliable function execution\n- 💬 **Modern Chat UI**: Clean, responsive interface with real-time streaming\n- 📚 **Session Management**: Local storage of chat sessions with full history\n- 🎨 **Markdown Support**: Rich text rendering with syntax highlighting\n- 🌐 **Tool Visualization**: Interactive displays for tool executions and results\n- ⚡ **Streaming Tools**: Real-time tool execution with streaming responses\n- 🐳 **Docker Ready**: Full containerization with Docker Compose\n- 🚀 **Production Ready**: Nginx-served frontend with Traefik labels\n\n## Quick Start\n\n### Prerequisites\n\n- Docker and Docker Compose\n- At least 4GB RAM for model execution\n\n\u003e **⚡ New in v2.0**: Native Ollama tool calling support! The agent now uses Ollama's built-in function calling API for more reliable and faster tool execution with streaming support.\n\n### 1. Clone and Setup\n\n```bash\ngit clone \u003cyour-repo\u003e\ncd chat-agent\n\n# Option 1: Create .env file (recommended for development)\ncp .env.example .env\n# Edit .env with your configuration\n\n# Option 2: Use environment variables directly (recommended for production)\nexport OLLAMA_URL=http://ollama:11434\n# OR\nexport ZHIPUAI_API_KEY=your_zhipu_api_key\n```\n\n### 2. Start Services\n\n```bash\ndocker-compose up -d\n```\n\nThis will start:\n- **Ollama** on port 11434\n- **Backend API** on port 8000  \n- **Frontend** on port 3000\n\n### 3. Pull a Model\n\n```bash\n# Pull a model (this may take a few minutes)\ndocker exec ollama ollama pull llama3.2\n\n# Or try other models with tool support:\n# docker exec ollama ollama pull llama3.1\n# docker exec ollama ollama pull qwen2.5\n```\n\n### 4. Access the Application\n\nOpen your browser and go to http://localhost:3000\n\n## Configuration\n\n### Environment Variables\n\nYou can configure the application using environment variables directly or with a `.env` file. At minimum, you need **one** of the following LLM providers:\n\n#### Required (at least one):\n```bash\n# For local Ollama instance\nOLLAMA_URL=http://ollama:11434\n\n# OR for Zhipu AI cloud service\nZHIPUAI_API_KEY=your_zhipu_api_key\n```\n\n#### Optional configuration:\nEdit `.env` to configure additional options:\n\n```bash\n# LLM Model Configuration\nLLM_MODEL=llama3.2                  # Choose your model\nOLLAMA_URL=http://ollama:11434      # Ollama service URL\nCORS_ORIGINS=http://localhost:3000,https://ccoreilly.github.io  # Allowed origins\n\n# Agent Configuration\nAGENT_TYPE=softcatala_english       # Agent type: softcatala_english (default) or softcatala_catalan\n\n# Production (for Traefik)\n# TRAEFIK_HOST=your-domain.com\n```\n\n### Agent Types\n\nThe system supports two different Softcatalà agent types that can be configured using the `AGENT_TYPE` environment variable:\n\n#### 🏴‍☠️ softcatala_english (Default)\n- **System Prompt**: English (for better LLM performance)\n- **Response Language**: Catalan only\n- **Purpose**: Optimized Softcatalà assistant with English instructions for better model comprehension\n- **Best For**: Production use with Catalan language support\n\n#### 🏴‍☠️ softcatala_catalan  \n- **System Prompt**: Catalan\n- **Response Language**: Catalan only\n- **Purpose**: Fully Catalan Softcatalà assistant \n- **Best For**: Testing prompt effectiveness in Catalan vs English\n\n**Usage Examples:**\n```bash\n# Use default Softcatalà agent (English prompt, Catalan responses)\nAGENT_TYPE=softcatala_english\n\n# Use fully Catalan Softcatalà agent\nAGENT_TYPE=softcatala_catalan\n```\n\n### Available Models\n\nPopular models you can use:\n\n- `llama3.1` - Latest model with native tool support (4.7GB) ⭐\n- `llama3.2` - Efficient with tool calling (2.0GB) ⭐\n- `qwen2.5` - Advanced model with excellent tool support (4.4GB) ⭐\n- `mistral` - Fast and efficient (4.1GB)\n- `codellama` - Code-focused (3.8GB)\n- `llama2:13b` - Larger model for better quality (7.3GB)\n\n⭐ **Recommended for tool usage** - These models have native training for function calling and provide the best experience with tools.\n\n## Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Frontend      │    │    Backend      │    │     Ollama      │\n│   (React)       │◄──►│   (FastAPI)     │◄──►│   (LLM Server)  │\n│   Port 3000     │    │   Port 8000     │    │   Port 11434    │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n```\n\n### Components\n\n- **Frontend**: React TypeScript app with local storage for chat sessions\n- **Backend**: FastAPI server with streaming responses and tool execution\n- **Agent**: LLM integration with tool calling capabilities\n- **Tools**: Extensible system with web browsing tool included\n- **Ollama**: Local LLM server for model inference\n\n## API Documentation\n\n### Endpoints\n\n- `GET /` - API status\n- `GET /health` - Health check with model info\n- `POST /chat/stream` - Streaming chat endpoint\n- `GET /models` - List available models\n\n### Chat API Example\n\n```bash\ncurl -X POST http://localhost:8000/chat/stream \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"messages\": [\n      {\"role\": \"user\", \"content\": \"Hello!\", \"timestamp\": \"2023-01-01T00:00:00Z\"}\n    ],\n    \"session_id\": \"session-123\"\n  }'\n```\n\n## Tool System\n\n### Available Tools\n\n#### Web Browser Tool\n- **Name**: `web_browser`\n- **Description**: Browse web pages and extract content\n- **Parameters**:\n  - `url` (required): URL to browse\n  - `extract_links` (optional): Extract links from page\n  - `max_content_length` (optional): Limit content length\n\n**Note**: Tools are now integrated using Ollama's native tool calling API instead of prompt-based approaches, providing better reliability and streaming support.\n\n### Adding Custom Tools\n\n1. Create a new tool class in `backend/tools/`:\n\n```python\nfrom .base import BaseTool, ToolDefinition, ToolParameter\n\nclass MyCustomTool(BaseTool):\n    @property\n    def definition(self) -\u003e ToolDefinition:\n        return ToolDefinition(\n            name=\"my_tool\",\n            description=\"Description of what the tool does\",\n            parameters=[\n                ToolParameter(\n                    name=\"param1\",\n                    type=\"string\", \n                    description=\"Parameter description\",\n                    required=True\n                )\n            ]\n        )\n    \n    async def execute(self, **kwargs):\n        # Tool implementation\n        return {\"result\": \"success\"}\n```\n\n2. Register the tool in `backend/main.py`:\n\n```python\nfrom tools.my_custom_tool import MyCustomTool\n\nmy_tool = MyCustomTool()\nagent = Agent(tools=[web_browser_tool, my_tool])\n```\n\n## Development\n\n### Local Development\n\nFor development with hot reload:\n\n```bash\n# Backend\ncd backend\npip install -r requirements.txt\nuvicorn main:app --reload --port 8000\n\n# Frontend  \ncd frontend\nnpm install\nnpm start\n```\n\n### Project Structure\n\n```\nchat-agent/\n├── backend/                 # FastAPI backend\n│   ├── main.py             # Main application\n│   ├── agent.py            # Agent implementation\n│   ├── tools/              # Tool implementations\n│   │   ├── base.py         # Base tool class\n│   │   └── web_browser.py  # Web browsing tool\n│   ├── requirements.txt    # Python dependencies\n│   └── Dockerfile         # Backend container\n├── frontend/               # React frontend\n│   ├── src/\n│   │   ├── components/     # UI components\n│   │   ├── hooks/         # Custom hooks\n│   │   ├── utils/         # Utilities\n│   │   └── types.ts       # TypeScript types\n│   ├── package.json       # Node dependencies\n│   └── Dockerfile        # Frontend container\n├── docker-compose.yml     # Service orchestration\n└── .env.example          # Environment template\n```\n\n## Production Deployment\n\n### With Traefik\n\nThe services include Traefik labels for production deployment:\n\n```yaml\n# docker-compose.prod.yml\nversion: '3.8'\nservices:\n  frontend:\n    labels:\n      - \"traefik.enable=true\"\n      - \"traefik.http.routers.chat-frontend.rule=Host(`your-domain.com`)\"\n      - \"traefik.http.routers.chat-frontend.entrypoints=websecure\"\n      - \"traefik.http.routers.chat-frontend.tls.certresolver=letsencrypt\"\n```\n\n### Environment Variables for Production\n\n```bash\nLLM_MODEL=llama3.2\nOLLAMA_URL=http://ollama:11434\nCORS_ORIGINS=https://your-domain.com\nTRAEFIK_HOST=your-domain.com\nAGENT_TYPE=softcatala_english\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Ollama not accessible**\n   ```bash\n   docker exec ollama ollama list  # Check if models are loaded\n   docker logs ollama              # Check Ollama logs\n   ```\n\n2. **Frontend can't connect to backend**\n   - Check CORS_ORIGINS in environment\n   - Verify backend is running on port 8000\n\n3. **Model not found**\n   ```bash\n   docker exec ollama ollama pull llama3.2  # Pull the model\n   ```\n\n4. **Out of memory**\n   - Try smaller models like `mistral`\n   - Increase Docker memory limit\n\n### Performance Tips\n\n- Use faster models like `mistral` for better response times\n- Increase model context length for longer conversations\n- Use SSD storage for faster model loading\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add your tool or feature\n4. Submit 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%2Fccoreilly%2Fagent-softcatala","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccoreilly%2Fagent-softcatala","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccoreilly%2Fagent-softcatala/lists"}