howler-agents-core 0.1.0__tar.gz

howler_agents_core-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Proto generated
+packages/howler-agents-service/src/howler_agents_service/generated/
+packages/howler-agents-ts/src/generated/
+packages/howler-agents-ui/src/generated/
+
+# Build output
+packages/howler-agents-ts/dist/
+packages/howler-agents-ui/.output/
+packages/howler-agents-ui/.vinxi/
+packages/howler-agents-docs/.output/
+packages/howler-agents-docs/.vinxi/
+
+# Docker
+.docker/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Claude Flow
+.claude-flow/
+.swarm/
+
+# Howler Agents local DB
+.howler-agents/
+
+# SWE-bench Docker evaluation reports (local artifacts)
+howler-agents__*.json
+logs/
+
+# Claude local DB
+.claude/memory.db
+
+# Misc
+*.log
+tmp/

howler_agents_core-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: howler-agents-core
+Version: 0.1.0
+Summary: Core library for Group-Evolving Agents
+Project-URL: Homepage, https://github.com/jbeck018/howler-agents
+Project-URL: Repository, https://github.com/jbeck018/howler-agents
+Project-URL: Documentation, https://github.com/jbeck018/howler-agents
+Project-URL: Bug Tracker, https://github.com/jbeck018/howler-agents/issues
+License: MIT
+Keywords: agent-evolution,gea,howler-agents,llm,multi-agent
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: claude-agent-sdk>=0.1.41
+Requires-Dist: click>=8.0
+Requires-Dist: litellm>=1.50.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.0
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: structlog>=24.0
+Provides-Extra: all
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: datasets>=2.0; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: pgvector>=0.3; extra == 'all'
+Requires-Dist: redis[hiredis]>=5.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
+Requires-Dist: swebench>=4.0; extra == 'all'
+Provides-Extra: bench
+Requires-Dist: datasets>=2.0; extra == 'bench'
+Requires-Dist: swebench>=4.0; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: httpx>=0.27; extra == 'mcp'
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: pgvector>=0.3; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# howler-agents-core
+
+Core Python library for Group-Evolving Agents (GEA) -- an evolutionary framework for open-ended self-improvement via experience sharing (arXiv:2602.04837).
+
+This package implements the full GEA algorithm: agent pool management, performance-novelty parent selection, shared experience aggregation, group reproduction via meta-LLM, and probe-based capability characterization. It can be used standalone or as the engine behind `howler-agents-service`.
+
+## Installation
+
+```bash
+pip install howler-agents-core
+```
+
+### Optional dependencies
+
+For production use with Postgres (experience store + pgvector KNN) and Redis (hot cache):
+
+```bash
+pip install howler-agents-core[postgres]   # SQLAlchemy + asyncpg + pgvector
+pip install howler-agents-core[redis]       # redis with hiredis
+pip install howler-agents-core[all]         # both
+```
+
+## Quick Usage
+
+```python
+import asyncio
+import uuid
+
+from howler_agents import HowlerConfig, EvolutionLoop
+from howler_agents.agents.base import Agent, AgentConfig, FrameworkPatch, TaskResult
+from howler_agents.agents.pool import AgentPool
+from howler_agents.evolution.reproducer import GroupReproducer
+from howler_agents.experience.pool import SharedExperiencePool
+from howler_agents.experience.store.memory import InMemoryStore
+from howler_agents.llm.router import LLMRouter
+from howler_agents.probes.evaluator import ProbeEvaluator
+from howler_agents.probes.registry import ProbeRegistry
+from howler_agents.selection.criterion import PerformanceNoveltySelector
+
+
+class MyAgent(Agent):
+    """Implement your agent by subclassing Agent."""
+
+    async def run_task(self, task: dict) -> TaskResult:
+        # Your task execution logic here
+        return TaskResult(success=True, score=0.8, output="done")
+
+    async def apply_patch(self, patch: FrameworkPatch) -> None:
+        self.patches.append(patch)
+
+
+async def main() -> None:
+    config = HowlerConfig(
+        population_size=10,
+        group_size=3,
+        num_iterations=5,
+        alpha=0.5,
+        num_probes=20,
+    )
+
+    store = InMemoryStore()
+    experience = SharedExperiencePool(store)
+    llm = LLMRouter(config)
+    selector = PerformanceNoveltySelector(alpha=config.alpha)
+    reproducer = GroupReproducer(llm, experience, config)
+    registry = ProbeRegistry()
+    registry.register_default_probes(num_probes=config.num_probes)
+    probes = ProbeEvaluator(registry)
+
+    pool = AgentPool()
+    for _ in range(config.population_size):
+        pool.add(MyAgent(AgentConfig(id=str(uuid.uuid4()))))
+
+    loop = EvolutionLoop(config, pool, selector, reproducer, experience, probes)
+
+    tasks = [{"description": "solve a coding problem", "type": "general"}]
+    results = await loop.run("my-run", tasks)
+    print(f"Best score: {results['best_score']:.3f}")
+
+
+asyncio.run(main())
+```
+
+## Core Modules
+
+| Module | Description |
+|---|---|
+| `howler_agents.agents` | Agent base class, AgentPool, FrameworkPatch |
+| `howler_agents.selection` | Performance scorer, KNN novelty estimator, combined criterion |
+| `howler_agents.experience` | Evolutionary traces, shared experience pool, pluggable stores |
+| `howler_agents.evolution` | Evolution directives, group reproducer, main evolution loop |
+| `howler_agents.probes` | Probe task interface, evaluator, registry |
+| `howler_agents.llm` | LiteLLM-backed router with role-based model dispatch |
+| `howler_agents.config` | `HowlerConfig` with all GEA parameters (K, M, alpha, iterations) |
+
+## Configuration
+
+`HowlerConfig` accepts all GEA parameters:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `population_size` (K) | 10 | Total agents in population |
+| `group_size` (M) | 3 | Agents per parent group |
+| `num_iterations` | 5 | Evolution generations |
+| `alpha` | 0.5 | Performance vs novelty weight (0=novelty, 1=performance) |
+| `num_probes` | 20 | Probe tasks for capability vector |
+| `task_domain` | "general" | Domain identifier (e.g., "swe-bench", "polyglot") |
+| `role_models` | Claude Sonnet defaults | Per-role LLM model configuration |
+
+## License
+
+MIT

howler_agents_core-0.1.0/README.md

@@ -0,0 +1,112 @@
+# howler-agents-core
+
+Core Python library for Group-Evolving Agents (GEA) -- an evolutionary framework for open-ended self-improvement via experience sharing (arXiv:2602.04837).
+
+This package implements the full GEA algorithm: agent pool management, performance-novelty parent selection, shared experience aggregation, group reproduction via meta-LLM, and probe-based capability characterization. It can be used standalone or as the engine behind `howler-agents-service`.
+
+## Installation
+
+```bash
+pip install howler-agents-core
+```
+
+### Optional dependencies
+
+For production use with Postgres (experience store + pgvector KNN) and Redis (hot cache):
+
+```bash
+pip install howler-agents-core[postgres]   # SQLAlchemy + asyncpg + pgvector
+pip install howler-agents-core[redis]       # redis with hiredis
+pip install howler-agents-core[all]         # both
+```
+
+## Quick Usage
+
+```python
+import asyncio
+import uuid
+
+from howler_agents import HowlerConfig, EvolutionLoop
+from howler_agents.agents.base import Agent, AgentConfig, FrameworkPatch, TaskResult
+from howler_agents.agents.pool import AgentPool
+from howler_agents.evolution.reproducer import GroupReproducer
+from howler_agents.experience.pool import SharedExperiencePool
+from howler_agents.experience.store.memory import InMemoryStore
+from howler_agents.llm.router import LLMRouter
+from howler_agents.probes.evaluator import ProbeEvaluator
+from howler_agents.probes.registry import ProbeRegistry
+from howler_agents.selection.criterion import PerformanceNoveltySelector
+
+
+class MyAgent(Agent):
+    """Implement your agent by subclassing Agent."""
+
+    async def run_task(self, task: dict) -> TaskResult:
+        # Your task execution logic here
+        return TaskResult(success=True, score=0.8, output="done")
+
+    async def apply_patch(self, patch: FrameworkPatch) -> None:
+        self.patches.append(patch)
+
+
+async def main() -> None:
+    config = HowlerConfig(
+        population_size=10,
+        group_size=3,
+        num_iterations=5,
+        alpha=0.5,
+        num_probes=20,
+    )
+
+    store = InMemoryStore()
+    experience = SharedExperiencePool(store)
+    llm = LLMRouter(config)
+    selector = PerformanceNoveltySelector(alpha=config.alpha)
+    reproducer = GroupReproducer(llm, experience, config)
+    registry = ProbeRegistry()
+    registry.register_default_probes(num_probes=config.num_probes)
+    probes = ProbeEvaluator(registry)
+
+    pool = AgentPool()
+    for _ in range(config.population_size):
+        pool.add(MyAgent(AgentConfig(id=str(uuid.uuid4()))))
+
+    loop = EvolutionLoop(config, pool, selector, reproducer, experience, probes)
+
+    tasks = [{"description": "solve a coding problem", "type": "general"}]
+    results = await loop.run("my-run", tasks)
+    print(f"Best score: {results['best_score']:.3f}")
+
+
+asyncio.run(main())
+```
+
+## Core Modules
+
+| Module | Description |
+|---|---|
+| `howler_agents.agents` | Agent base class, AgentPool, FrameworkPatch |
+| `howler_agents.selection` | Performance scorer, KNN novelty estimator, combined criterion |
+| `howler_agents.experience` | Evolutionary traces, shared experience pool, pluggable stores |
+| `howler_agents.evolution` | Evolution directives, group reproducer, main evolution loop |
+| `howler_agents.probes` | Probe task interface, evaluator, registry |
+| `howler_agents.llm` | LiteLLM-backed router with role-based model dispatch |
+| `howler_agents.config` | `HowlerConfig` with all GEA parameters (K, M, alpha, iterations) |
+
+## Configuration
+
+`HowlerConfig` accepts all GEA parameters:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `population_size` (K) | 10 | Total agents in population |
+| `group_size` (M) | 3 | Agents per parent group |
+| `num_iterations` | 5 | Evolution generations |
+| `alpha` | 0.5 | Performance vs novelty weight (0=novelty, 1=performance) |
+| `num_probes` | 20 | Probe tasks for capability vector |
+| `task_domain` | "general" | Domain identifier (e.g., "swe-bench", "polyglot") |
+| `role_models` | Claude Sonnet defaults | Per-role LLM model configuration |
+
+## License
+
+MIT

howler_agents_core-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "howler-agents-core"
+version = "0.1.0"
+description = "Core library for Group-Evolving Agents"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+keywords = ["howler-agents", "gea", "agent-evolution", "llm", "multi-agent"]
+dependencies = [
+    "litellm>=1.50.0",
+    "numpy>=1.26",
+    "scikit-learn>=1.4",
+    "pydantic>=2.0",
+    "structlog>=24.0",
+    "click>=8.0",
+    "aiosqlite>=0.20",
+    "claude-agent-sdk>=0.1.41",
+]
+
+[project.scripts]
+howler-agents = "howler_agents.cli:cli"
+
+[project.optional-dependencies]
+postgres = ["sqlalchemy[asyncio]>=2.0", "asyncpg>=0.29", "pgvector>=0.3"]
+redis = ["redis[hiredis]>=5.0"]
+mcp = ["mcp>=1.0", "httpx>=0.27"]
+bench = ["datasets>=2.0", "swebench>=4.0"]
+all = ["howler-agents-core[postgres,redis,mcp,bench]"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "pytest-mock>=3.12", "coverage>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/jbeck018/howler-agents"
+Repository = "https://github.com/jbeck018/howler-agents"
+Documentation = "https://github.com/jbeck018/howler-agents"
+"Bug Tracker" = "https://github.com/jbeck018/howler-agents/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/howler_agents"]

howler_agents_core-0.1.0/src/howler_agents/__init__.py

@@ -0,0 +1,7 @@
+"""Howler Agents - Group-Evolving Agents core library."""
+
+from howler_agents.config import HowlerConfig
+from howler_agents.evolution.loop import EvolutionLoop
+
+__all__ = ["EvolutionLoop", "HowlerConfig"]
+__version__ = "0.1.0"

howler_agents_core-0.1.0/src/howler_agents/agents/__init__.py

@@ -0,0 +1 @@
+""""""

howler_agents_core-0.1.0/src/howler_agents/agents/base.py

@@ -0,0 +1,82 @@
+"""Abstract base agent and configuration."""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class AgentConfig:
+    """Configuration state of a single agent."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    generation: int = 0
+    parent_id: str | None = None
+    group_id: str | None = None
+    framework_config: dict[str, Any] = field(default_factory=dict)
+    lineage: list[str] = field(default_factory=list)  # full ancestor chain, newest first
+
+
+@dataclass
+class TaskResult:
+    """Result from an agent performing a task."""
+
+    success: bool
+    score: float
+    output: str = ""
+    key_decisions: list[str] = field(default_factory=list)
+    lessons_learned: list[str] = field(default_factory=list)
+
+
+class Agent(ABC):
+    """Abstract base for an evolvable agent."""
+
+    def __init__(self, config: AgentConfig) -> None:
+        self.config = config
+        self.performance_score: float = 0.0
+        self.novelty_score: float = 0.0
+        self.combined_score: float = 0.0
+        self.capability_vector: list[float] = []
+        self.patches: list[FrameworkPatch] = []
+
+    @property
+    def id(self) -> str:
+        return self.config.id
+
+    @abstractmethod
+    async def run_task(self, task: dict[str, Any]) -> TaskResult:
+        """Execute a task and return the result."""
+        ...
+
+    @abstractmethod
+    async def apply_patch(self, patch: FrameworkPatch) -> None:
+        """Apply an evolutionary mutation to this agent."""
+        ...
+
+    def clone(self, new_id: str | None = None) -> AgentConfig:
+        """Create a child config from this agent."""
+        new_lineage = [self.config.id, *list(self.config.lineage)]
+        return AgentConfig(
+            id=new_id or str(uuid.uuid4()),
+            generation=self.config.generation + 1,
+            parent_id=self.config.id,
+            group_id=self.config.group_id,
+            framework_config=dict(self.config.framework_config),
+            lineage=new_lineage,
+        )
+
+
+@dataclass
+class FrameworkPatch:
+    """A code/workflow mutation applied to an agent."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    agent_id: str = ""
+    generation: int = 0
+    intent: str = ""
+    diff: str = ""
+    category: str = "general"
+    config_updates: dict[str, Any] = field(default_factory=dict)

howler_agents_core-0.1.0/src/howler_agents/agents/pool.py

@@ -0,0 +1,50 @@
+"""Agent population pool management."""
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Sequence
+
+from howler_agents.agents.base import Agent
+
+
+class AgentPool:
+    """Manages a living population of agents."""
+
+    def __init__(self) -> None:
+        self._agents: dict[str, Agent] = {}
+
+    def add(self, agent: Agent) -> None:
+        self._agents[agent.id] = agent
+
+    def remove(self, agent_id: str) -> Agent | None:
+        return self._agents.pop(agent_id, None)
+
+    def get(self, agent_id: str) -> Agent | None:
+        return self._agents.get(agent_id)
+
+    @property
+    def agents(self) -> list[Agent]:
+        return list(self._agents.values())
+
+    @property
+    def size(self) -> int:
+        return len(self._agents)
+
+    def top_k(self, k: int, key: str = "combined_score") -> list[Agent]:
+        """Return the top-K agents by the given score attribute."""
+        return heapq.nlargest(k, self._agents.values(), key=lambda a: getattr(a, key, 0.0))
+
+    def by_generation(self, generation: int) -> list[Agent]:
+        return [a for a in self._agents.values() if a.config.generation == generation]
+
+    def partition_groups(self, group_size: int) -> list[list[Agent]]:
+        """Partition current population into groups of given size."""
+        agents = list(self._agents.values())
+        return [agents[i : i + group_size] for i in range(0, len(agents), group_size)]
+
+    def replace_population(self, new_agents: Sequence[Agent]) -> None:
+        """Replace the entire population."""
+        self._agents.clear()
+        for agent in new_agents:
+            self._agents[agent.id] = agent

howler_agents_core-0.1.0/src/howler_agents/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""SWE-Bench and other benchmark harnesses for howler-agents."""