dialectus-engine 0.2.2__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. {dialectus_engine-0.2.2/dialectus_engine.egg-info → dialectus_engine-0.3.1}/PKG-INFO +1 -1
  2. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/__init__.py +1 -1
  3. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/config/settings.py +41 -16
  4. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/context_builder.py +11 -7
  5. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/engine.py +18 -18
  6. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/prompt_builder.py +34 -29
  7. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/response_handler.py +2 -3
  8. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/round_manager.py +33 -30
  9. dialectus_engine-0.3.1/dialectus/engine/debate_engine/types.py +99 -0
  10. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/utils.py +11 -6
  11. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/judges/ai_judge.py +85 -67
  12. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/judges/base.py +32 -43
  13. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/judges/ensemble_utils.py +44 -29
  14. dialectus_engine-0.3.1/dialectus/engine/models/__init__.py +17 -0
  15. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/manager.py +14 -10
  16. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_filter_config.py +3 -1
  17. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/base_model_provider.py +34 -12
  18. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/ollama_provider.py +9 -9
  19. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/open_router_provider.py +95 -55
  20. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/openrouter_generation_types.py +44 -3
  21. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/moderation/llm_moderator.py +15 -12
  22. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/moderation/openai_moderator.py +21 -19
  23. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1/dialectus_engine.egg-info}/PKG-INFO +1 -1
  24. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/pyproject.toml +2 -1
  25. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_moderation_openai.py +102 -8
  26. dialectus_engine-0.2.2/dialectus/engine/debate_engine/types.py +0 -23
  27. dialectus_engine-0.2.2/dialectus/engine/models/__init__.py +0 -1
  28. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/LICENSE +0 -0
  29. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/README.md +0 -0
  30. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/__init__.py +0 -0
  31. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/config/__init__.py +0 -0
  32. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/config/openrouter_filters.json +0 -0
  33. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/__init__.py +0 -0
  34. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/judge_coordinator.py +0 -0
  35. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/debate_engine/models.py +0 -0
  36. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/__init__.py +0 -0
  37. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/base.py +0 -0
  38. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/oxford.py +0 -0
  39. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/parliamentary.py +0 -0
  40. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/public_forum.py +0 -0
  41. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/registry.py +0 -0
  42. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/socratic.py +0 -0
  43. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/formats/topic_themes.py +0 -0
  44. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/judges/__init__.py +0 -0
  45. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/judges/factory.py +0 -0
  46. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/base_types.py +0 -0
  47. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/cache_manager.py +0 -0
  48. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_architecture.py +0 -0
  49. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_capability_extractor.py +0 -0
  50. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_enhanced_model_info.py +0 -0
  51. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_model.py +0 -0
  52. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_model_filter.py +0 -0
  53. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_models_response.py +0 -0
  54. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_pricing.py +0 -0
  55. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/openrouter/openrouter_top_provider.py +0 -0
  56. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/__init__.py +0 -0
  57. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/exceptions.py +0 -0
  58. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/models/providers/providers.py +0 -0
  59. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/moderation/__init__.py +0 -0
  60. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/moderation/base_moderator.py +0 -0
  61. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/moderation/exceptions.py +0 -0
  62. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus/engine/moderation/manager.py +0 -0
  63. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus_engine.egg-info/SOURCES.txt +0 -0
  64. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus_engine.egg-info/dependency_links.txt +0 -0
  65. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus_engine.egg-info/requires.txt +0 -0
  66. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/dialectus_engine.egg-info/top_level.txt +0 -0
  67. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/setup.cfg +0 -0
  68. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_cache_manager.py +0 -0
  69. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_config_settings.py +0 -0
  70. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_debate_models.py +0 -0
  71. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_format_registry.py +0 -0
  72. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_formats_base.py +0 -0
  73. {dialectus_engine-0.2.2 → dialectus_engine-0.3.1}/tests/test_judges_factory.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dialectus-engine
3
- Version: 0.2.2
3
+ Version: 0.3.1
4
4
  Summary: Dialectus AI debate engine framework
5
5
  Author: Dialectus AI
6
6
  License-Expression: MIT
@@ -4,4 +4,4 @@ from pkgutil import extend_path
4
4
 
5
5
  __path__ = extend_path(__path__, __name__)
6
6
  __all__: list[str] = []
7
- __version__ = "0.2.2"
7
+ __version__ = "0.3.1"
@@ -6,6 +6,25 @@ from typing import Literal
6
6
  from pydantic import BaseModel, Field, field_validator
7
7
 
8
8
 
9
+ def validate_provider_value(value: str, valid_providers: set[str]) -> str:
10
+ """Validate provider string against allowed values.
11
+
12
+ Args:
13
+ value: Provider name to validate
14
+ valid_providers: Set of valid provider names
15
+
16
+ Returns:
17
+ Lowercase provider name
18
+
19
+ Raises:
20
+ ValueError: If provider is not in valid_providers
21
+ """
22
+ normalized = value.lower()
23
+ if normalized not in valid_providers:
24
+ raise ValueError(f"Provider must be one of: {valid_providers}")
25
+ return normalized
26
+
27
+
9
28
  class ModelConfig(BaseModel):
10
29
  """Configuration for a debate model."""
11
30
 
@@ -24,11 +43,8 @@ class ModelConfig(BaseModel):
24
43
 
25
44
  @field_validator("provider")
26
45
  @classmethod
27
- def validate_provider(cls, v: str):
28
- valid_providers = {"ollama", "openrouter"}
29
- if v not in valid_providers:
30
- raise ValueError(f"Provider must be one of: {valid_providers}")
31
- return v
46
+ def validate_provider(cls, v: str) -> str:
47
+ return validate_provider_value(v, {"ollama", "openrouter"})
32
48
 
33
49
 
34
50
  class DebateConfig(BaseModel):
@@ -93,9 +109,9 @@ class ModerationConfig(BaseModel):
93
109
 
94
110
  @field_validator("provider")
95
111
  @classmethod
96
- def validate_provider(cls, v: str):
112
+ def validate_provider(cls, v: str) -> str:
97
113
  # Provider names are case-insensitive
98
- # Ollama and openrouter have automatic URL/key resolution
114
+ # For moderation, we accept any provider (ollama, openrouter, openai, custom)
99
115
  # Custom providers require explicit base_url
100
116
  return v.lower()
101
117
 
@@ -183,11 +199,8 @@ class SystemConfig(BaseModel):
183
199
 
184
200
  @field_validator("debate_topic_source")
185
201
  @classmethod
186
- def validate_topic_source(cls, v: str):
187
- valid_sources = {"ollama", "openrouter"}
188
- if v not in valid_sources:
189
- raise ValueError(f"debate_topic_source must be one of: {valid_sources}")
190
- return v
202
+ def validate_topic_source(cls, v: str) -> str:
203
+ return validate_provider_value(v, {"ollama", "openrouter"})
191
204
 
192
205
 
193
206
  class AppConfig(BaseModel):
@@ -203,14 +216,26 @@ class AppConfig(BaseModel):
203
216
 
204
217
  @classmethod
205
218
  def load_from_file(cls, config_path: Path) -> "AppConfig":
206
- """Load configuration from JSON file."""
219
+ """Load configuration from JSON file.
220
+
221
+ Args:
222
+ config_path: Path to the JSON configuration file
223
+
224
+ Returns:
225
+ AppConfig instance loaded from the file
226
+
227
+ Raises:
228
+ FileNotFoundError: If config file doesn't exist
229
+ ValueError: If required sections are missing or invalid
230
+ """
207
231
  if not config_path.exists():
208
232
  raise FileNotFoundError(f"Config file not found: {config_path}")
209
233
 
234
+ # Use Pydantic's built-in JSON validation
210
235
  import json
211
236
 
212
- with open(config_path, encoding="utf-8") as f:
213
- data = json.load(f)
237
+ json_data = config_path.read_text(encoding="utf-8")
238
+ data = json.loads(json_data)
214
239
 
215
240
  # Validate required sections
216
241
  required_sections = ["debate", "models", "judging", "system"]
@@ -226,7 +251,7 @@ class AppConfig(BaseModel):
226
251
  "Config must include at least one model in 'models' section"
227
252
  )
228
253
 
229
- return cls(**data)
254
+ return cls.model_validate(data)
230
255
 
231
256
 
232
257
  def get_default_config() -> AppConfig:
@@ -2,9 +2,10 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from typing import TYPE_CHECKING
5
+ from typing import TYPE_CHECKING, cast
6
6
 
7
7
  from dialectus.engine.config.settings import AppConfig
8
+ from dialectus.engine.models.providers.base_model_provider import ChatMessage
8
9
 
9
10
  from .models import DebateContext
10
11
  from .prompt_builder import PromptBuilder
@@ -13,6 +14,9 @@ from .types import DebatePhase
13
14
  if TYPE_CHECKING:
14
15
  from dialectus.engine.formats import DebateFormat, FormatPhase
15
16
 
17
+ # Maximum number of recent messages to include in conversation context
18
+ MAX_CONTEXT_MESSAGES = 6
19
+
16
20
 
17
21
  class ContextBuilder:
18
22
  """Builds conversation context for model prompts during debates."""
@@ -39,7 +43,7 @@ class ContextBuilder:
39
43
  speaker_id: str,
40
44
  phase: DebatePhase,
41
45
  context: DebateContext,
42
- ) -> list[dict[str, str]]:
46
+ ) -> list[ChatMessage]:
43
47
  """Build conversation context for the model.
44
48
 
45
49
  Args:
@@ -71,7 +75,7 @@ class ContextBuilder:
71
75
  })
72
76
 
73
77
  # Add relevant debate history
74
- for msg in context.messages[-6:]: # Last 6 messages for context
78
+ for msg in context.messages[-MAX_CONTEXT_MESSAGES:]:
75
79
  role = "assistant" if msg.speaker_id == speaker_id else "user"
76
80
 
77
81
  # Use a cleaner format that's less likely to be repeated by small
@@ -94,14 +98,14 @@ class ContextBuilder:
94
98
  )
95
99
  messages.append({"role": "user", "content": turn_prompt})
96
100
 
97
- return messages
101
+ return cast(list[ChatMessage], messages)
98
102
 
99
103
  def build_format_conversation_context(
100
104
  self,
101
105
  speaker_id: str,
102
106
  format_phase: FormatPhase,
103
107
  context: DebateContext,
104
- ) -> list[dict[str, str]]:
108
+ ) -> list[ChatMessage]:
105
109
  """Build conversation context for the model using format phase.
106
110
 
107
111
  Args:
@@ -139,7 +143,7 @@ class ContextBuilder:
139
143
  })
140
144
 
141
145
  # Add relevant debate history
142
- for msg in context.messages[-6:]: # Last 6 messages for context
146
+ for msg in context.messages[-MAX_CONTEXT_MESSAGES:]:
143
147
  role = "assistant" if msg.speaker_id == speaker_id else "user"
144
148
 
145
149
  # Use a cleaner format that's less likely to be repeated by small
@@ -160,4 +164,4 @@ class ContextBuilder:
160
164
  turn_prompt = f"Now speak as {role_name}. Stay under {word_limit} words."
161
165
  messages.append({"role": "user", "content": turn_prompt})
162
166
 
163
- return messages
167
+ return cast(list[ChatMessage], messages)
@@ -3,7 +3,6 @@
3
3
  import asyncio
4
4
  import logging
5
5
  import time
6
- from collections.abc import Awaitable, Callable
7
6
  from typing import Any
8
7
 
9
8
  from dialectus.engine.config.settings import AppConfig
@@ -17,7 +16,14 @@ from .models import DebateContext
17
16
  from .prompt_builder import PromptBuilder
18
17
  from .response_handler import ResponseHandler
19
18
  from .round_manager import RoundManager
20
- from .types import DebatePhase
19
+ from .types import (
20
+ ChunkCallback,
21
+ DebatePhase,
22
+ MessageEventCallback,
23
+ PhaseEventCallback,
24
+ PhaseEventType,
25
+ PhaseStartedEventData,
26
+ )
21
27
 
22
28
  logger = logging.getLogger(__name__)
23
29
 
@@ -102,11 +108,9 @@ class DebateEngine:
102
108
 
103
109
  async def run_full_debate(
104
110
  self,
105
- phase_callback: Callable[[str, dict[str, Any]], Awaitable[None]] | None = None,
106
- message_callback: (
107
- Callable[[str, dict[str, Any]], Awaitable[None]] | None
108
- ) = None,
109
- chunk_callback: Callable[[str, bool], Awaitable[None]] | None = None,
111
+ phase_callback: PhaseEventCallback | None = None,
112
+ message_callback: MessageEventCallback | None = None,
113
+ chunk_callback: ChunkCallback | None = None,
110
114
  ) -> DebateContext:
111
115
  """Run a complete debate from start to finish.
112
116
 
@@ -166,18 +170,14 @@ class DebateEngine:
166
170
 
167
171
  # Invoke phase callback if provided
168
172
  if phase_callback:
169
- await phase_callback(
170
- "phase_started",
171
- {
172
- "phase": format_phase.name,
173
- "instruction": format_phase.instruction,
174
- "current_phase": self.context.current_round,
175
- "total_phases": total_phases,
176
- "progress_percentage": round(
177
- (phase_index / total_phases) * 100
178
- ),
179
- },
173
+ phase_event = PhaseStartedEventData(
174
+ phase=format_phase.name,
175
+ instruction=format_phase.instruction,
176
+ current_phase=self.context.current_round,
177
+ total_phases=total_phases,
178
+ progress_percentage=round((phase_index / total_phases) * 100),
180
179
  )
180
+ await phase_callback(PhaseEventType.PHASE_STARTED, phase_event)
181
181
 
182
182
  # If streaming callbacks provided, use streaming version
183
183
  if message_callback or chunk_callback:
@@ -3,6 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import logging
6
+ from textwrap import dedent
6
7
  from typing import TYPE_CHECKING
7
8
 
8
9
  from dialectus.engine.config.settings import AppConfig
@@ -78,31 +79,33 @@ class PromptBuilder:
78
79
  """
79
80
  format_instructions = self.format.get_format_instructions()
80
81
 
81
- return f"""You are participating in a formal debate about: "{context.topic}"
82
+ return dedent(f"""
83
+ You are participating in a formal debate about: "{context.topic}"
82
84
 
83
- DEBATE FORMAT: {self.format.name.upper()}
84
- WORD LIMIT: {self.config.debate.word_limit} words or less per response
85
+ DEBATE FORMAT: {self.format.name.upper()}
86
+ WORD LIMIT: {self.config.debate.word_limit} words or less per response
85
87
 
86
- {format_instructions}
88
+ {format_instructions}
87
89
 
88
- GENERAL RULES:
89
- 1. Stay focused on the topic
90
- 2. Keep your response under {self.config.debate.word_limit} words
91
- 3. Provide evidence and reasoning
92
- 4. Address opponent's arguments
93
- 5. Maintain a respectful tone
94
- 6. Follow the debate format structure
90
+ GENERAL RULES:
91
+ 1. Stay focused on the topic
92
+ 2. Keep your response under {self.config.debate.word_limit} words
93
+ 3. Provide evidence and reasoning
94
+ 4. Address opponent's arguments
95
+ 5. Maintain a respectful tone
96
+ 6. Follow the debate format structure
95
97
 
96
- RESPONSE FORMAT:
97
- - Speak directly as your assigned role without any labels, prefixes, or announcements
98
- - Use plain text without markdown formatting (avoid **bold**, *italics*, # headers,
99
- bullet points)
100
- - Write in natural conversational style as if speaking live to an audience
101
- - Do not add labels like "COUNTER:", "STATEMENT:", "OPENING:", etc. - just speak
102
- your argument
103
- - Focus on content, not formatting or structure
98
+ RESPONSE FORMAT:
99
+ - Speak directly as your assigned role without any labels, prefixes, or announcements
100
+ - Use plain text without markdown formatting (avoid **bold**, *italics*, # headers,
101
+ bullet points)
102
+ - Write in natural conversational style as if speaking live to an audience
103
+ - Do not add labels like "COUNTER:", "STATEMENT:", "OPENING:", etc. - just speak
104
+ your argument
105
+ - Focus on content, not formatting or structure
104
106
 
105
- You will be told your specific role and speaking context for each response."""
107
+ You will be told your specific role and speaking context for each response.
108
+ """).strip()
106
109
 
107
110
  def _create_participant_prompt(
108
111
  self,
@@ -166,18 +169,20 @@ You will be told your specific role and speaking context for each response."""
166
169
  personality, "Speak in your natural style."
167
170
  )
168
171
 
169
- return f"""{base_prompt}
172
+ return dedent(f"""
173
+ {base_prompt}
170
174
 
171
- YOUR ROLE: {role_instruction}
172
- You are not describing what {role_name} would say - you ARE {role_name} speaking
173
- directly. Speak as if you are standing at the podium addressing the audience.
174
- Do not announce your role, add labels, or use prefixes like "COUNTER:" or
175
- "STATEMENT:" - simply speak your argument.
175
+ YOUR ROLE: {role_instruction}
176
+ You are not describing what {role_name} would say - you ARE {role_name} speaking
177
+ directly. Speak as if you are standing at the podium addressing the audience.
178
+ Do not announce your role, add labels, or use prefixes like "COUNTER:" or
179
+ "STATEMENT:" - simply speak your argument.
176
180
 
177
- YOUR SPEAKING STYLE: {style_instruction}
181
+ YOUR SPEAKING STYLE: {style_instruction}
178
182
 
179
- Remember: You are embodying the {role_name} position throughout this debate.
180
- Speak naturally and directly as that person would speak."""
183
+ Remember: You are embodying the {role_name} position throughout this debate.
184
+ Speak naturally and directly as that person would speak.
185
+ """).strip()
181
186
 
182
187
  @staticmethod
183
188
  def get_phase_instruction(phase: DebatePhase) -> str:
@@ -6,7 +6,6 @@ import asyncio
6
6
  import logging
7
7
  import re
8
8
  import time
9
- from collections.abc import Awaitable, Callable
10
9
  from typing import TYPE_CHECKING
11
10
 
12
11
  from dialectus.engine.config.settings import AppConfig
@@ -15,7 +14,7 @@ from dialectus.engine.models.providers import ProviderRateLimitError
15
14
 
16
15
  from .context_builder import ContextBuilder
17
16
  from .models import DebateContext, DebateMessage
18
- from .types import DebatePhase, Position
17
+ from .types import ChunkCallback, DebatePhase, Position
19
18
  from .utils import calculate_max_tokens, query_and_update_cost, trim_incomplete_sentence
20
19
 
21
20
  if TYPE_CHECKING:
@@ -186,7 +185,7 @@ class ResponseHandler:
186
185
  speaker_id: str,
187
186
  format_phase: FormatPhase,
188
187
  context: DebateContext,
189
- chunk_callback: Callable[[str, bool], Awaitable[None]],
188
+ chunk_callback: ChunkCallback,
190
189
  message_id: str | None = None,
191
190
  ) -> DebateMessage:
192
191
  """Get a streaming response from a specific speaker using format phase.
@@ -4,12 +4,19 @@ from __future__ import annotations
4
4
 
5
5
  import logging
6
6
  import uuid
7
- from collections.abc import Awaitable, Callable
8
- from typing import TYPE_CHECKING, Any
7
+ from typing import TYPE_CHECKING
9
8
 
10
9
  from .models import DebateContext, DebateMessage
11
10
  from .response_handler import ResponseHandler
12
- from .types import DebatePhase, Position
11
+ from .types import (
12
+ ChunkCallback,
13
+ DebatePhase,
14
+ MessageCompleteEventData,
15
+ MessageEventCallback,
16
+ MessageEventType,
17
+ MessageStartEventData,
18
+ Position,
19
+ )
13
20
 
14
21
  if TYPE_CHECKING:
15
22
  from formats import DebateFormat, FormatPhase
@@ -96,10 +103,8 @@ class RoundManager:
96
103
  self,
97
104
  format_phase: FormatPhase,
98
105
  context: DebateContext,
99
- message_callback: (
100
- Callable[[str, dict[str, Any]], Awaitable[None]] | None
101
- ) = None,
102
- chunk_callback: Callable[[str, bool], Awaitable[None]] | None = None,
106
+ message_callback: MessageEventCallback | None = None,
107
+ chunk_callback: ChunkCallback | None = None,
103
108
  ) -> list[DebateMessage]:
104
109
  """Conduct a round with streaming callbacks.
105
110
 
@@ -126,16 +131,14 @@ class RoundManager:
126
131
 
127
132
  # Call message_start callback
128
133
  if message_callback:
129
- await message_callback(
130
- "message_start",
131
- {
132
- "message_id": message_id,
133
- "speaker_id": speaker_id,
134
- "position": speaker_position.value,
135
- "phase": format_phase.phase.value,
136
- "round_number": context.current_round,
137
- },
134
+ start_event = MessageStartEventData(
135
+ message_id=message_id,
136
+ speaker_id=speaker_id,
137
+ position=speaker_position.value,
138
+ phase=format_phase.phase.value,
139
+ round_number=context.current_round,
138
140
  )
141
+ await message_callback(MessageEventType.MESSAGE_START, start_event)
139
142
 
140
143
  # Create streaming wrapper that calls chunk_callback
141
144
  async def chunk_wrapper(chunk: str, is_complete: bool):
@@ -151,21 +154,21 @@ class RoundManager:
151
154
 
152
155
  # Call message_complete callback
153
156
  if message_callback:
157
+ complete_event = MessageCompleteEventData(
158
+ message_id=message_id,
159
+ speaker_id=message.speaker_id,
160
+ position=message.position.value,
161
+ phase=message.phase.value,
162
+ round_number=message.round_number,
163
+ content=message.content,
164
+ timestamp=message.timestamp.isoformat(),
165
+ word_count=len(message.content.split()),
166
+ metadata=message.metadata,
167
+ cost=message.cost,
168
+ generation_id=message.generation_id,
169
+ )
154
170
  await message_callback(
155
- "message_complete",
156
- {
157
- "message_id": message_id,
158
- "speaker_id": message.speaker_id,
159
- "position": message.position.value,
160
- "phase": message.phase.value,
161
- "round_number": message.round_number,
162
- "content": message.content,
163
- "timestamp": message.timestamp.isoformat(),
164
- "word_count": len(message.content.split()),
165
- "metadata": message.metadata,
166
- "cost": message.cost,
167
- "generation_id": message.generation_id,
168
- },
171
+ MessageEventType.MESSAGE_COMPLETE, complete_event
169
172
  )
170
173
 
171
174
  logger.info(
@@ -0,0 +1,99 @@
1
+ """Shared types and enums for the debate engine."""
2
+
3
+ from collections.abc import Awaitable, Callable
4
+ from enum import Enum
5
+ from typing import Protocol
6
+
7
+ from pydantic import BaseModel
8
+
9
+
10
+ class PhaseEventType(str, Enum):
11
+ """Event types for phase callbacks."""
12
+
13
+ PHASE_STARTED = "phase_started"
14
+ PHASE_COMPLETED = "phase_completed"
15
+
16
+
17
+ class MessageEventType(str, Enum):
18
+ """Event types for message callbacks."""
19
+
20
+ MESSAGE_START = "message_start"
21
+ MESSAGE_COMPLETE = "message_complete"
22
+
23
+
24
+ class PhaseStartedEventData(BaseModel):
25
+ """Data structure for phase_started event callbacks."""
26
+
27
+ phase: str
28
+ instruction: str
29
+ current_phase: int
30
+ total_phases: int
31
+ progress_percentage: int
32
+
33
+
34
+ class MessageStartEventData(BaseModel):
35
+ """Data structure for message_start event callbacks."""
36
+
37
+ message_id: str
38
+ speaker_id: str
39
+ position: str
40
+ phase: str
41
+ round_number: int
42
+
43
+
44
+ class MessageCompleteEventData(BaseModel):
45
+ """Data structure for message_complete event callbacks."""
46
+
47
+ message_id: str
48
+ speaker_id: str
49
+ position: str
50
+ content: str
51
+ phase: str
52
+ round_number: int
53
+ timestamp: str
54
+ word_count: int
55
+ metadata: dict[str, str]
56
+ cost: float | None = None
57
+ generation_id: str | None = None
58
+
59
+
60
+ # Callback protocols with proper type narrowing
61
+ class PhaseEventCallback(Protocol):
62
+ """Protocol for phase event callbacks with type-safe event data."""
63
+
64
+ async def __call__(
65
+ self, event: PhaseEventType, data: PhaseStartedEventData
66
+ ) -> None: ...
67
+
68
+
69
+ class MessageEventCallback(Protocol):
70
+ """Protocol for message event callbacks with type-safe event data."""
71
+
72
+ async def __call__(
73
+ self,
74
+ event: MessageEventType,
75
+ data: MessageStartEventData | MessageCompleteEventData,
76
+ ) -> None: ...
77
+
78
+
79
+ type ChunkCallback = Callable[[str, bool], Awaitable[None]]
80
+
81
+
82
+ class DebatePhase(Enum):
83
+ """Phases of a debate."""
84
+
85
+ SETUP = "setup"
86
+ OPENING = "opening"
87
+ REBUTTAL = "rebuttal"
88
+ CROSS_EXAM = "cross_examination"
89
+ CLOSING = "closing"
90
+ EVALUATION = "evaluation"
91
+ COMPLETED = "completed"
92
+
93
+
94
+ class Position(Enum):
95
+ """Debate positions."""
96
+
97
+ PRO = "pro"
98
+ CON = "con"
99
+ NEUTRAL = "neutral"
@@ -10,6 +10,14 @@ from .models import DebateMessage
10
10
 
11
11
  logger = logging.getLogger(__name__)
12
12
 
13
+ # Token calculation constants
14
+ # Average tokens per word ratio (1 token ≈ 0.75 words, so multiply words by 1.33)
15
+ TOKENS_PER_WORD_RATIO = 1.33
16
+ # Buffer for sentence completion in words
17
+ SENTENCE_BUFFER_WORDS = 100
18
+ # Buffer for sentence completion in tokens (100 words * 1.33)
19
+ SENTENCE_BUFFER_TOKENS = 133
20
+
13
21
 
14
22
  def calculate_max_tokens(word_limit: int) -> int:
15
23
  """Calculate maximum tokens based on word limit with buffer for incomplete
@@ -19,13 +27,10 @@ def calculate_max_tokens(word_limit: int) -> int:
19
27
  word_limit: Maximum number of words allowed
20
28
 
21
29
  Returns:
22
- Maximum number of tokens with ~100 word buffer (1 token ≈ 0.75 words)
30
+ Maximum number of tokens with buffer for sentence completion
23
31
  """
24
- # Base conversion: word_limit * 1.33 (since 1 token ≈ 0.75 words)
25
- # Add buffer: ~100 words = 133 tokens
26
- base_tokens = int(word_limit * 1.33)
27
- buffer_tokens = 133 # ~100 words of buffer for sentence completion
28
- return base_tokens + buffer_tokens
32
+ base_tokens = int(word_limit * TOKENS_PER_WORD_RATIO)
33
+ return base_tokens + SENTENCE_BUFFER_TOKENS
29
34
 
30
35
 
31
36
  def trim_incomplete_sentence(text: str) -> str: