Metadata-Version: 2.4
Name: polymathera-colony
Version: 0.1.0
Summary: Polymathera's no-RAG, multi-agent framework for extremely long, dense contexts (1B+ tokens).
License: Apache-2.0
License-File: LICENSE
Keywords: multi-agent,llm,context,cache-aware,agents,no-rag
Author: Ahmed Nassar
Author-email: amam.nassar@gmail.com
Requires-Python: >=3.11,<3.13
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Provides-Extra: aws
Provides-Extra: cache-compression
Provides-Extra: code-analysis
Provides-Extra: cpu
Provides-Extra: dashboard
Provides-Extra: distributed
Provides-Extra: gpu
Provides-Extra: observability
Requires-Dist: aiobotocore (>=2.13.0,<3.0.0) ; extra == "aws"
Requires-Dist: aiofiles (>=25.1.0,<26.0.0)
Requires-Dist: aiohttp (>=3.13.3,<4.0.0)
Requires-Dist: aiokafka (>=0.12.0,<0.13.0) ; extra == "observability"
Requires-Dist: anthropic (>=0.79.0,<0.80.0) ; extra == "cpu"
Requires-Dist: astor (>=0.8.1,<0.9.0) ; extra == "code-analysis"
Requires-Dist: asyncpg (>=0.31.0,<0.32.0)
Requires-Dist: boto3 (>=1.35.0,<2.0.0) ; extra == "aws"
Requires-Dist: botocore (>=1.35.0,<2.0.0) ; extra == "aws"
Requires-Dist: cachetools (>=7.0.0,<8.0.0)
Requires-Dist: chardet (>=5.2.0,<6.0.0) ; extra == "code-analysis"
Requires-Dist: chromadb (>=1.0.0,<2.0.0) ; extra == "cpu"
Requires-Dist: circuitbreaker (>=2.1.3,<3.0.0)
Requires-Dist: colorama (>=0.4.6,<0.5.0)
Requires-Dist: docker (>=7.1.0,<8.0.0)
Requires-Dist: etcd3 (>=0.12.0,<0.13.0) ; extra == "distributed"
Requires-Dist: fastapi (>=0.115) ; extra == "dashboard"
Requires-Dist: gitpython (>=3.1.46,<4.0.0) ; extra == "code-analysis"
Requires-Dist: html2text (>=2025.4.15,<2026.0.0) ; extra == "code-analysis"
Requires-Dist: httpx (>=0.27) ; extra == "dashboard"
Requires-Dist: ipython (>=9.10.0,<10.0.0)
Requires-Dist: markdown (>=3.10.1,<4.0.0) ; extra == "code-analysis"
Requires-Dist: msgpack (>=1.1.2,<2.0.0)
Requires-Dist: multipledispatch (>=1.0.0,<2.0.0)
Requires-Dist: nbformat (>=5.10.4,<6.0.0) ; extra == "code-analysis"
Requires-Dist: networkx (>=3.6.1,<4.0.0)
Requires-Dist: numpy (>=1.21.0,<2.3)
Requires-Dist: openai (>=2.21.0,<3.0.0) ; extra == "cpu"
Requires-Dist: opentelemetry-api (>=1.36.0,<2.0.0)
Requires-Dist: overrides (>=7.7.0,<8.0.0)
Requires-Dist: pillow (>=12.1.0,<13.0.0) ; extra == "code-analysis"
Requires-Dist: prometheus-client (>=0.21.0,<0.22.0)
Requires-Dist: psutil (>=7.2.2,<8.0.0) ; extra == "code-analysis"
Requires-Dist: pygithub (>=2.8.1,<3.0.0) ; extra == "code-analysis"
Requires-Dist: pynvml (>=13.0.1,<14.0.0) ; extra == "gpu"
Requires-Dist: python-louvain (>=0.16,<0.17) ; extra == "code-analysis"
Requires-Dist: python-magic (>=0.4.27,<0.5.0) ; extra == "code-analysis"
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: ray[data,serve,train,tune] (==2.49.0)
Requires-Dist: redis (>=7.1.0,<8.0.0)
Requires-Dist: rich (>=14.3.2,<15.0.0)
Requires-Dist: sentence-transformers (>=5.2.2,<6.0.0) ; extra == "cpu"
Requires-Dist: sqlalchemy (>=2.0.46,<3.0.0)
Requires-Dist: sqlmodel (>=0.0.32,<0.0.33)
Requires-Dist: sqlparse (>=0.5.5,<0.6.0) ; extra == "code-analysis"
Requires-Dist: tenacity (>=9.1.3,<10.0.0)
Requires-Dist: termcolor (>=3.3.0,<4.0.0)
Requires-Dist: tiktoken (>=0.12.0,<0.13.0)
Requires-Dist: toml (>=0.10.2,<0.11.0) ; extra == "code-analysis"
Requires-Dist: torch (==2.8.0+cu128) ; extra == "gpu"
Requires-Dist: torchaudio (==2.8.0+cu128) ; extra == "gpu"
Requires-Dist: torchvision (==0.23.0+cu128) ; extra == "gpu"
Requires-Dist: transformers (>=4.52.4,<5.0.0) ; extra == "gpu"
Requires-Dist: tree-sitter (>=0.25.2,<0.26.0) ; extra == "code-analysis"
Requires-Dist: typer[all] (>=0.15.0,<0.16.0)
Requires-Dist: uvicorn[standard] (>=0.30) ; extra == "dashboard"
Requires-Dist: vllm (>=0.11.0,<0.12.0) ; extra == "gpu"
Requires-Dist: xxhash (>=3.6.0,<4.0.0) ; extra == "code-analysis"
Requires-Dist: zstandard (>=0.25.0,<0.26.0) ; extra == "cache-compression"
Project-URL: Homepage, https://github.com/polymathera/colony
Project-URL: Repository, https://github.com/polymathera/colony
Description-Content-Type: text/markdown

# Colony

Polymathera's no-RAG, multi-agent framework for extremely long, *dense* contexts (1B+ tokens). It provides:

- A cluster-level **virtual context memory** with user-defined context paging.
- Cache-aware agent action policies.
- Powerful and composable multi-agent patterns.
- Arbitrarily sophisticated memory hierarchies and cognitive processes.

> Can Polymathera's Colony be a realization of the "_country of geniuses in a datacenter_" vision?


## Quick Start

### Installation

```bash
pip install polymathera-colony
```

With optional extras:

```bash
pip install polymathera-colony[code_analysis]    # Code analysis tools
pip install polymathera-colony[gpu]              # GPU inference (vLLM, PyTorch)
pip install polymathera-colony[cpu]              # CPU-only inference (Anthropic API)
pip install polymathera-colony --all-extras      # Everything
```

### Local Test Environment

Colony ships with `colony-env`, a CLI tool that spins up a local Ray cluster + Redis using Docker Compose. The only prerequisite is **Docker**.

```bash
# Start the cluster (builds image on first run)
colony-env up

# Generate a sample analysis config
polymath init-config --output my_analysis.yaml

# Run a code analysis over a local codebase
colony-env run /path/to/codebase --config my_analysis.yaml

# Check service status
colony-env status

# Open the web dashboard
colony-env dashboard

# Scale workers
colony-env up --workers 3

# Tear down
colony-env down

# Verify prerequisites
colony-env doctor
```

All Colony dependencies run inside Docker — no local GPU drivers, Ray, or Redis installation required. The `colony-env run` command copies your codebase to be analyzed into the cluster and executes inside the Ray head container with full access to the framework.

**Services started by `colony-env up`:**

| Service | Port | Description |
|---------|------|-------------|
| Colony dashboard | `localhost:8080` | Web UI for agents, sessions, VCM |
| Ray dashboard | `localhost:8265` | Cluster monitoring UI |
| Ray client | `localhost:10001` | Ray client connection |
| Redis | `localhost:6379` | State management backend |

### Web Dashboard

The Colony dashboard starts automatically with `colony-env up` at [localhost:8080](http://localhost:8080). It provides:

- **Overview** — cluster health, application deployments, quick stats
- **Agents** — list registered agents, view state, capabilities, and details
- **Sessions** — browse sessions and their agent runs with token usage
- **VCM** — page table, working set, and virtual context statistics

```bash
# Run the agent colony
colony-env down && colony-env up --workers 3 && colony-env run --local-repo /path/to/codebase --config my_analysis.yaml --verbose

# Open the dashboard in your browser
colony-env dashboard

# Use a custom port (must match COLONY_DASHBOARD_UI_PORT)
colony-env dashboard --port 9090
```

For frontend development, run the Vite dev server on the host with hot-reload:

```bash
cd src/polymathera/colony/web_ui/frontend
npm install
npm run dev     # Starts on localhost:5173, proxies /api to localhost:8080
```

## Development

```bash
git clone https://github.com/polymathera/colony.git
cd colony
poetry install --all-extras
```

### Optional Dependencies

Dependencies that require system libraries (CUDA, native extensions) are declared as optional extras in `pyproject.toml`:

```toml
[tool.poetry.dependencies]
some-dep = { version = "^1.0", optional = true }

[tool.poetry.extras]
feature_name = ["some-dep"]
```

Guard optional imports in code:

```python
try:
    import heavy_dep
except ImportError:
    heavy_dep = None

def feature_function():
    if heavy_dep is None:
        raise ImportError(
            "Install with: pip install polymathera-colony[feature_name]"
        )
```

### Documentation

Documentation is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and API reference is auto-generated from docstrings via [mkdocstrings](https://mkdocstrings.github.io/).

```bash
# Install dev dependencies (includes mkdocs + plugins)
poetry install --all-extras

# Start local docs server with hot-reload
mkdocs serve                  # --dev-addr http://127.0.0.1:8000/

# Build static site (output in site/)
mkdocs build

# Build with strict mode (treat warnings as errors)
mkdocs build --strict
```

> The server has **hot-reload** — any edits to `docs/` or source files will auto-rebuild.


