Metadata-Version: 2.4
Name: gathering
Version: 0.5.0
Summary: A collaborative multi-agent AI framework for autonomous AI agents working together
License: MIT
License-File: LICENSE
Keywords: ai,agents,multi-agent,llm,framework,collaboration,autonomous,rag
Author: Loc Cosnier
Author-email: loc.cosnier@pm.me
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Provides-Extra: all
Provides-Extra: rag
Provides-Extra: redis
Requires-Dist: aiofiles (>=23.0,<24.0)
Requires-Dist: alembic (>=1.13,<2.0)
Requires-Dist: anthropic (>=0.40,<0.41)
Requires-Dist: asyncpg (>=0.29,<0.30)
Requires-Dist: bcrypt (>=4.0.0,<4.1.0)
Requires-Dist: croniter (>=2.0,<3.0)
Requires-Dist: fastapi (>=0.109,<0.110)
Requires-Dist: httpx (>=0.26,<0.27)
Requires-Dist: openai (>=1.0,<2.0)
Requires-Dist: passlib[bcrypt] (>=1.7,<2.0)
Requires-Dist: psutil (>=5.9,<6.0)
Requires-Dist: pycopg (>=0.1.0,<0.2.0)
Requires-Dist: pydantic-settings (>=2.0,<3.0)
Requires-Dist: pydantic[email] (>=2.0,<3.0)
Requires-Dist: python-dotenv (>=1.0,<2.0)
Requires-Dist: python-jose[cryptography] (>=3.3,<4.0)
Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
Requires-Dist: sqlalchemy[asyncio] (>=2.0,<3.0)
Requires-Dist: structlog (>=24.0,<25.0)
Requires-Dist: tenacity (>=8.2,<9.0)
Requires-Dist: uvicorn[standard] (>=0.27,<0.28)
Requires-Dist: websockets (>=12.0,<13.0)
Project-URL: Documentation, https://gathering.readthedocs.io
Project-URL: Homepage, https://github.com/alkimya/gathering
Project-URL: Repository, https://github.com/alkimya/gathering
Description-Content-Type: text/markdown

# GatheRing ䷬

A collaborative multi-agent AI framework built with Python, FastAPI, and React.

## Overview

GatheRing is a highly customizable and modular framework for creating and managing AI agents with complex personalities, diverse competencies, and professional expertise. Agents can collaborate in "Circles", use external tools, and be managed through a web dashboard.

## Key Features

- **Multi-Model Support**: Anthropic (Claude), OpenAI, DeepSeek, and local models via Ollama
- **Gathering Circles**: Team orchestration with task routing, reviews, and conflict detection
- **Agent Persistence**: Personas, memory, sessions with automatic context injection
- **Agent Conversations**: Direct inter-agent collaboration with turn strategies
- **REST API**: Full FastAPI backend with WebSocket support
- **React Dashboard**: Modern Web3 dark theme UI for agents, circles, tasks, and conversations
- **RAG Support**: PostgreSQL + pgvector for semantic memory search
- **Knowledge Base**: Semantic search across documentation and best practices
- **Skills System**: 18+ skills (filesystem, git, code, shell, database, http, etc.) with per-agent configuration
- **Agent Autonomy**: Background tasks, scheduled actions, goal management
- **Settings UI**: Configure API keys and application parameters via dashboard
- **Authentication**: JWT-based auth with token revocation and OWASP security headers
- **Fully Tested**: 1071 tests with TDD approach

## Quick Start

```bash
# Clone the repository
git clone https://github.com/alkimya/gathering.git
cd gathering

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys and database credentials

# Setup database (PostgreSQL + pgvector)
python -m gathering.db.setup

# Run tests
pytest tests/ -v

# Start the API server
uvicorn gathering.api:app --reload

# Start the dashboard (in another terminal)
cd dashboard
npm install
npm run dev
```

## Architecture

```text
gathering/
├── core/           # Core abstractions and config
├── agents/         # Agent persistence (persona, memory, session)
├── orchestration/  # Circles, Facilitator, Events
├── llm/            # LLM providers (Anthropic, OpenAI, DeepSeek, Ollama)
├── skills/         # Tools (Git, Test, etc.)
├── api/            # FastAPI REST API + WebSocket
├── rag/            # RAG services (embeddings, vector store, memory)
└── db/             # Database models (PostgreSQL + pgvector)

dashboard/          # React + TypeScript + Tailwind (Web3 Dark Theme)
├── src/
│   ├── pages/      # Dashboard, Agents, Circles, Tasks, Schedules, Goals, Settings
│   ├── services/   # API client
│   └── hooks/      # WebSocket hook
```

## Documentation

- [User Guide](docs/user/guide.md) - Getting started guide
- [Dashboard Guide](docs/user/dashboard.md) - Web dashboard documentation
- [Architecture](docs/developer/architecture.md) - Technical documentation
- [API Reference](docs/api/endpoints.md) - REST API documentation
- [Contributing](docs/developer/contributing.md) - Developer guide

## Stack

| Component | Technology |
|-----------|------------|
| Backend | Python 3.11+, FastAPI, Pydantic |
| Frontend | React 19, TypeScript, Tailwind CSS, Vite |
| Database | PostgreSQL 16 + pgvector |
| DB Layer | [pycopg](https://pypi.org/project/pycopg/) - High-level PostgreSQL API (asyncpg + psycopg) |
| LLM | Anthropic, OpenAI, DeepSeek, Mistral, Google, Ollama |
| Embeddings | OpenAI text-embedding-3-small (1536 dims) |

## Environment Variables

```bash
# Required
DATABASE_URL=postgresql://user:pass@localhost:5432/gathering
OPENAI_API_KEY=sk-...          # For embeddings + OpenAI models

# Optional LLM providers
ANTHROPIC_API_KEY=sk-ant-...   # For Claude models
DEEPSEEK_API_KEY=sk-...        # For DeepSeek models
OLLAMA_HOST=http://localhost:11434  # For local models

# Dashboard
VITE_API_URL=http://localhost:8000  # API URL for frontend

# Authentication (production)
SECRET_KEY=your-secret-key-min-32-chars  # JWT signing key
ADMIN_EMAIL=admin@example.com            # Admin email
ADMIN_PASSWORD_HASH=$2b$12$...           # Bcrypt hash of admin password
```

## API Overview

```text
GET  /health                       # Health check
GET  /agents                       # List agents
POST /agents                       # Create agent
POST /agents/{id}/chat             # Chat with agent
GET  /circles                      # List circles
POST /circles/{name}/tasks         # Create task
POST /conversations                # Start conversation
POST /memories/agents/{id}/recall  # Semantic memory search
POST /memories/knowledge/search    # Knowledge base search
GET  /background-tasks             # List background tasks
POST /background-tasks             # Create background task
GET  /scheduled-actions            # List scheduled actions
POST /scheduled-actions            # Create scheduled action
GET  /goals                        # List agent goals
POST /goals                        # Create goal
GET  /settings                     # Get configuration
PATCH /settings/providers/{name}   # Update provider settings
POST /auth/login                   # Authenticate user
POST /auth/logout                  # Revoke token
WS   /ws?token=<jwt>               # Real-time updates (authenticated)
```

Full API docs at `/docs` (Swagger) or `/redoc` when server is running.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contact

- GitHub: [alkimya/gathering](https://github.com/alkimya/gathering)
- Email: [loc.cosnier@pm.me](mailto:loc.cosnier@pm.me)

