dialectus-engine 0.1.2__tar.gz → 0.2.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 (74) hide show
  1. {dialectus_engine-0.1.2/dialectus_engine.egg-info → dialectus_engine-0.2.1}/PKG-INFO +166 -9
  2. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/README.md +161 -6
  3. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/__init__.py +1 -1
  4. dialectus_engine-0.2.1/dialectus/engine/config/__init__.py +1 -0
  5. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/config/settings.py +65 -5
  6. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/__init__.py +1 -1
  7. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/context_builder.py +37 -35
  8. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/engine.py +49 -16
  9. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/judge_coordinator.py +8 -6
  10. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/prompt_builder.py +42 -15
  11. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/response_handler.py +56 -26
  12. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/round_manager.py +30 -24
  13. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/types.py +3 -1
  14. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/utils.py +16 -12
  15. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/__init__.py +1 -1
  16. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/base.py +11 -2
  17. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/oxford.py +65 -22
  18. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/parliamentary.py +57 -17
  19. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/public_forum.py +84 -33
  20. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/registry.py +8 -3
  21. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/formats/socratic.py +78 -32
  22. dialectus_engine-0.2.1/dialectus/engine/formats/topic_themes.py +357 -0
  23. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/judges/__init__.py +2 -2
  24. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/judges/ai_judge.py +96 -51
  25. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/judges/ensemble_utils.py +20 -8
  26. dialectus_engine-0.2.1/dialectus/engine/models/__init__.py +1 -0
  27. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/base_types.py +4 -2
  28. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/manager.py +42 -40
  29. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_capability_extractor.py +11 -9
  30. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_enhanced_model_info.py +10 -6
  31. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_filter_config.py +7 -4
  32. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_model_filter.py +25 -27
  33. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_models_response.py +1 -1
  34. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_pricing.py +0 -1
  35. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_top_provider.py +0 -1
  36. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/__init__.py +1 -1
  37. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/exceptions.py +3 -1
  38. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/ollama_provider.py +5 -4
  39. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/open_router_provider.py +78 -27
  40. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/openrouter_generation_types.py +10 -4
  41. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/providers.py +2 -1
  42. dialectus_engine-0.2.1/dialectus/engine/moderation/__init__.py +6 -0
  43. dialectus_engine-0.2.1/dialectus/engine/moderation/base_moderator.py +52 -0
  44. dialectus_engine-0.2.1/dialectus/engine/moderation/exceptions.py +55 -0
  45. dialectus_engine-0.2.1/dialectus/engine/moderation/llm_moderator.py +209 -0
  46. dialectus_engine-0.2.1/dialectus/engine/moderation/manager.py +194 -0
  47. dialectus_engine-0.2.1/dialectus/engine/moderation/openai_moderator.py +152 -0
  48. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1/dialectus_engine.egg-info}/PKG-INFO +166 -9
  49. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus_engine.egg-info/SOURCES.txt +20 -1
  50. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus_engine.egg-info/requires.txt +1 -1
  51. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/pyproject.toml +32 -4
  52. dialectus_engine-0.2.1/tests/test_cache_manager.py +189 -0
  53. dialectus_engine-0.2.1/tests/test_config_settings.py +117 -0
  54. dialectus_engine-0.2.1/tests/test_debate_models.py +88 -0
  55. dialectus_engine-0.2.1/tests/test_format_registry.py +576 -0
  56. dialectus_engine-0.2.1/tests/test_formats_base.py +119 -0
  57. dialectus_engine-0.2.1/tests/test_judges_factory.py +146 -0
  58. dialectus_engine-0.2.1/tests/test_moderation_openai.py +230 -0
  59. dialectus_engine-0.1.2/dialectus/engine/config/__init__.py +0 -1
  60. dialectus_engine-0.1.2/dialectus/engine/formats/topic_themes.py +0 -233
  61. dialectus_engine-0.1.2/dialectus/engine/models/__init__.py +0 -1
  62. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/LICENSE +0 -0
  63. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/__init__.py +0 -0
  64. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/config/openrouter_filters.json +0 -0
  65. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/debate_engine/models.py +0 -0
  66. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/judges/base.py +0 -0
  67. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/judges/factory.py +0 -0
  68. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/cache_manager.py +2 -2
  69. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_architecture.py +0 -0
  70. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/openrouter/openrouter_model.py +0 -0
  71. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus/engine/models/providers/base_model_provider.py +0 -0
  72. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus_engine.egg-info/dependency_links.txt +0 -0
  73. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/dialectus_engine.egg-info/top_level.txt +0 -0
  74. {dialectus_engine-0.1.2 → dialectus_engine-0.2.1}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dialectus-engine
3
- Version: 0.1.2
3
+ Version: 0.2.1
4
4
  Summary: Dialectus AI debate engine framework
5
5
  Author: Dialectus AI
6
6
  License-Expression: MIT
@@ -12,21 +12,23 @@ Classifier: Development Status :: 4 - Beta
12
12
  Classifier: Intended Audience :: Developers
13
13
  Classifier: Intended Audience :: Education
14
14
  Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
15
16
  Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
16
18
  Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
17
19
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
- Requires-Python: >=3.13
20
+ Requires-Python: >=3.12
19
21
  Description-Content-Type: text/markdown
20
22
  License-File: LICENSE
21
23
  Requires-Dist: httpx>=0.28.1
22
24
  Requires-Dist: openai>=1.105.0
23
25
  Requires-Dist: pydantic>=2.11.7
24
26
  Provides-Extra: dev
25
- Requires-Dist: pip-tools; extra == "dev"
26
27
  Requires-Dist: ruff>=0.5.0; extra == "dev"
27
28
  Requires-Dist: pytest>=7.0; extra == "dev"
28
29
  Requires-Dist: twine; extra == "dev"
29
30
  Requires-Dist: build; extra == "dev"
31
+ Requires-Dist: pyright>=1.1.377; extra == "dev"
30
32
  Dynamic: license-file
31
33
 
32
34
  <img src="https://raw.githubusercontent.com/dialectus-ai/dialectus-engine/main/assets/logo.png" alt="Dialectus Engine" width="350">
@@ -37,7 +39,7 @@ Dynamic: license-file
37
39
 
38
40
  A Python library for orchestrating AI-powered debates with multi-provider model support.
39
41
 
40
- ![Python](https://img.shields.io/badge/python-3.13+-blue.svg)
42
+ ![Python](https://img.shields.io/badge/python-3.12+-blue.svg)
41
43
  ![License](https://img.shields.io/badge/license-MIT-green.svg)
42
44
  ![Status](https://img.shields.io/badge/status-Production%20Ready-brightgreen.svg)
43
45
 
@@ -52,17 +54,38 @@ The Dialectus Engine is a standalone Python library that provides core debate or
52
54
  - **Configuration** (`config/`) - System configuration management
53
55
  - **Judges** (`judges/`) - AI judge implementations with ensemble support
54
56
  - **Formats** (`formats/`) - Debate format definitions (Oxford, Parliamentary, Socratic, Public Forum)
57
+ - **Moderation** (`moderation/`) - Optional content safety system for debate topics
55
58
 
56
59
  ## Installation
57
60
 
58
61
  ### From PyPI
59
62
 
63
+ **Using uv (recommended):**
64
+ ```bash
65
+ uv pip install dialectus-engine
66
+ ```
67
+
68
+ **Using pip:**
60
69
  ```bash
61
70
  pip install dialectus-engine
62
71
  ```
63
72
 
64
73
  ### From Source
65
74
 
75
+ **Using uv (recommended, faster):**
76
+ ```bash
77
+ # Clone the repository
78
+ git clone https://github.com/dialectus-ai/dialectus-engine.git
79
+ cd dialectus-engine
80
+
81
+ # Install in development mode with all dev dependencies
82
+ uv sync
83
+
84
+ # Or install without dev dependencies
85
+ uv pip install -e .
86
+ ```
87
+
88
+ **Using pip:**
66
89
  ```bash
67
90
  # Clone the repository
68
91
  git clone https://github.com/dialectus-ai/dialectus-engine.git
@@ -77,15 +100,22 @@ pip install -e ".[dev]"
77
100
 
78
101
  ### As a Dependency
79
102
 
80
- Add to your `requirements.txt` or `pyproject.toml`:
103
+ Add to your `pyproject.toml`:
81
104
 
82
- ```
83
- dialectus-engine>=0.1.0
105
+ ```toml
106
+ [project]
107
+ dependencies = [
108
+ "dialectus-engine>=0.1.0",
109
+ ]
84
110
  ```
85
111
 
86
112
  Or install directly from git:
87
113
 
88
114
  ```bash
115
+ # Using uv
116
+ uv pip install git+https://github.com/dialectus-ai/dialectus-engine.git@main
117
+
118
+ # Using pip
89
119
  pip install git+https://github.com/dialectus-ai/dialectus-engine.git@main
90
120
  ```
91
121
 
@@ -126,11 +156,16 @@ asyncio.run(run_debate())
126
156
  The engine uses `debate_config.json` for system configuration. To get started:
127
157
 
128
158
  ```bash
129
- # Copy the example configuration
159
+ # Linux/Mac: Copy the example configuration
130
160
  cp debate_config.example.json debate_config.json
131
161
 
162
+ # Windows (PowerShell):
163
+ # copy debate_config.example.json debate_config.json
164
+
132
165
  # Edit with your settings and API keys
133
- nano debate_config.json
166
+ # Linux/Mac: nano debate_config.json
167
+ # Windows: notepad debate_config.json
168
+ # Or use your preferred editor (VS Code, vim, etc.)
134
169
  ```
135
170
 
136
171
  Key configuration sections:
@@ -138,9 +173,102 @@ Key configuration sections:
138
173
  - **Providers**: Configure Ollama (local) and OpenRouter (cloud) settings
139
174
  - **Judging**: Set evaluation criteria and judge models
140
175
  - **Debate**: Default topic, format, and word limits
176
+ - **Moderation** (optional): Content safety for user-provided topics
141
177
 
142
178
  For detailed configuration documentation, see [CONFIG_GUIDE.md](CONFIG_GUIDE.md).
143
179
 
180
+ ## Development Workflows
181
+
182
+ ### Running Tests and Type Checking
183
+
184
+ **Using uv (recommended):**
185
+ ```bash
186
+ # Run tests
187
+ uv run pytest
188
+
189
+ # Type check with Pyright
190
+ uv run pyright
191
+
192
+ # Lint with ruff
193
+ uv run ruff check .
194
+
195
+ # Format with ruff
196
+ uv run ruff format .
197
+ ```
198
+
199
+ **Using pip:**
200
+ ```bash
201
+ # Ensure dev dependencies are installed
202
+ pip install -e ".[dev]"
203
+
204
+ # Run tests
205
+ pytest
206
+
207
+ # Type check with Pyright
208
+ pyright
209
+
210
+ # Lint and format
211
+ ruff check .
212
+ ruff format .
213
+ ```
214
+
215
+ ### Building Distribution
216
+
217
+ **Using uv:**
218
+ ```bash
219
+ # Build wheel and sdist
220
+ uv build
221
+
222
+ # Install locally from wheel
223
+ uv pip install dist/dialectus_engine-*.whl
224
+ ```
225
+
226
+ **Using pip:**
227
+ ```bash
228
+ # Build wheel and sdist
229
+ python -m build
230
+
231
+ # Install locally
232
+ pip install dist/dialectus_engine-*.whl
233
+ ```
234
+
235
+ ### Managing Dependencies
236
+
237
+ **Using uv:**
238
+ ```bash
239
+ # Add a new dependency
240
+ # 1. Edit pyproject.toml [project.dependencies] section
241
+ # 2. Update lock file and sync environment:
242
+ uv lock && uv sync
243
+
244
+ # Upgrade all dependencies (within version constraints)
245
+ uv lock --upgrade
246
+
247
+ # Upgrade specific package
248
+ uv lock --upgrade-package httpx
249
+
250
+ # Add dev dependency
251
+ # 1. Edit pyproject.toml [project.optional-dependencies.dev]
252
+ # 2. Run:
253
+ uv sync
254
+ ```
255
+
256
+ **Using pip:**
257
+ ```bash
258
+ # Add a new dependency
259
+ # 1. Edit pyproject.toml dependencies
260
+ # 2. Reinstall:
261
+ pip install -e ".[dev]"
262
+ ```
263
+
264
+ ### Why uv?
265
+
266
+ - **10-100x faster** than pip for installs and resolution
267
+ - **Reproducible builds** via `uv.lock` (cross-platform, includes hashes)
268
+ - **Python 3.14 ready** - Takes advantage of free-threading for even better performance
269
+ - **Single source of truth** - Dependencies in `pyproject.toml`, lock file auto-generated
270
+ - **Compatible** - `pip` still works perfectly with `pyproject.toml`
271
+
144
272
  ## Features
145
273
 
146
274
  ### Multi-Provider Model Support
@@ -162,6 +290,12 @@ For detailed configuration documentation, see [CONFIG_GUIDE.md](CONFIG_GUIDE.md)
162
290
  - **Structured decisions**: JSON-serializable judge results
163
291
  - **Configurable criteria**: Logic, evidence, persuasiveness, etc.
164
292
 
293
+ ### Content Moderation (Optional)
294
+ - **Multi-provider support**: Ollama (local), OpenRouter, OpenAI moderation API
295
+ - **Safety categories**: Harassment, hate speech, violence, sexual content, dangerous activities
296
+ - **Flexible deployment**: Enable for production APIs, disable for trusted environments
297
+ - **Graceful error handling**: Provider-specific rate limit handling and retry logic
298
+
165
299
  ## Architecture
166
300
 
167
301
  Key architectural principles:
@@ -218,3 +352,26 @@ judge = JudgeFactory.create_judge(config.judging, model_manager)
218
352
  # Get aggregated decision
219
353
  decision = await judge.judge_debate(context)
220
354
  ```
355
+
356
+ ### Content Moderation
357
+
358
+ ```python
359
+ from dialectus.engine.moderation import ModerationManager, TopicRejectedError
360
+
361
+ # Create moderation manager
362
+ manager = ModerationManager(config.moderation, config.system)
363
+
364
+ # Validate user-provided topic
365
+ user_topic = "Should AI be regulated?"
366
+
367
+ try:
368
+ result = await manager.moderate_topic(user_topic)
369
+ # Topic is safe, proceed with debate
370
+ print(f"Topic approved with confidence: {result.confidence}")
371
+ except TopicRejectedError as e:
372
+ # Topic violates content policy
373
+ print(f"Topic rejected: {e.reason}")
374
+ print(f"Violated categories: {', '.join(e.categories)}")
375
+ ```
376
+
377
+ For comprehensive moderation testing and setup instructions, see [MODERATION_TESTING.md](MODERATION_TESTING.md).
@@ -6,7 +6,7 @@
6
6
 
7
7
  A Python library for orchestrating AI-powered debates with multi-provider model support.
8
8
 
9
- ![Python](https://img.shields.io/badge/python-3.13+-blue.svg)
9
+ ![Python](https://img.shields.io/badge/python-3.12+-blue.svg)
10
10
  ![License](https://img.shields.io/badge/license-MIT-green.svg)
11
11
  ![Status](https://img.shields.io/badge/status-Production%20Ready-brightgreen.svg)
12
12
 
@@ -21,17 +21,38 @@ The Dialectus Engine is a standalone Python library that provides core debate or
21
21
  - **Configuration** (`config/`) - System configuration management
22
22
  - **Judges** (`judges/`) - AI judge implementations with ensemble support
23
23
  - **Formats** (`formats/`) - Debate format definitions (Oxford, Parliamentary, Socratic, Public Forum)
24
+ - **Moderation** (`moderation/`) - Optional content safety system for debate topics
24
25
 
25
26
  ## Installation
26
27
 
27
28
  ### From PyPI
28
29
 
30
+ **Using uv (recommended):**
31
+ ```bash
32
+ uv pip install dialectus-engine
33
+ ```
34
+
35
+ **Using pip:**
29
36
  ```bash
30
37
  pip install dialectus-engine
31
38
  ```
32
39
 
33
40
  ### From Source
34
41
 
42
+ **Using uv (recommended, faster):**
43
+ ```bash
44
+ # Clone the repository
45
+ git clone https://github.com/dialectus-ai/dialectus-engine.git
46
+ cd dialectus-engine
47
+
48
+ # Install in development mode with all dev dependencies
49
+ uv sync
50
+
51
+ # Or install without dev dependencies
52
+ uv pip install -e .
53
+ ```
54
+
55
+ **Using pip:**
35
56
  ```bash
36
57
  # Clone the repository
37
58
  git clone https://github.com/dialectus-ai/dialectus-engine.git
@@ -46,15 +67,22 @@ pip install -e ".[dev]"
46
67
 
47
68
  ### As a Dependency
48
69
 
49
- Add to your `requirements.txt` or `pyproject.toml`:
70
+ Add to your `pyproject.toml`:
50
71
 
51
- ```
52
- dialectus-engine>=0.1.0
72
+ ```toml
73
+ [project]
74
+ dependencies = [
75
+ "dialectus-engine>=0.1.0",
76
+ ]
53
77
  ```
54
78
 
55
79
  Or install directly from git:
56
80
 
57
81
  ```bash
82
+ # Using uv
83
+ uv pip install git+https://github.com/dialectus-ai/dialectus-engine.git@main
84
+
85
+ # Using pip
58
86
  pip install git+https://github.com/dialectus-ai/dialectus-engine.git@main
59
87
  ```
60
88
 
@@ -95,11 +123,16 @@ asyncio.run(run_debate())
95
123
  The engine uses `debate_config.json` for system configuration. To get started:
96
124
 
97
125
  ```bash
98
- # Copy the example configuration
126
+ # Linux/Mac: Copy the example configuration
99
127
  cp debate_config.example.json debate_config.json
100
128
 
129
+ # Windows (PowerShell):
130
+ # copy debate_config.example.json debate_config.json
131
+
101
132
  # Edit with your settings and API keys
102
- nano debate_config.json
133
+ # Linux/Mac: nano debate_config.json
134
+ # Windows: notepad debate_config.json
135
+ # Or use your preferred editor (VS Code, vim, etc.)
103
136
  ```
104
137
 
105
138
  Key configuration sections:
@@ -107,9 +140,102 @@ Key configuration sections:
107
140
  - **Providers**: Configure Ollama (local) and OpenRouter (cloud) settings
108
141
  - **Judging**: Set evaluation criteria and judge models
109
142
  - **Debate**: Default topic, format, and word limits
143
+ - **Moderation** (optional): Content safety for user-provided topics
110
144
 
111
145
  For detailed configuration documentation, see [CONFIG_GUIDE.md](CONFIG_GUIDE.md).
112
146
 
147
+ ## Development Workflows
148
+
149
+ ### Running Tests and Type Checking
150
+
151
+ **Using uv (recommended):**
152
+ ```bash
153
+ # Run tests
154
+ uv run pytest
155
+
156
+ # Type check with Pyright
157
+ uv run pyright
158
+
159
+ # Lint with ruff
160
+ uv run ruff check .
161
+
162
+ # Format with ruff
163
+ uv run ruff format .
164
+ ```
165
+
166
+ **Using pip:**
167
+ ```bash
168
+ # Ensure dev dependencies are installed
169
+ pip install -e ".[dev]"
170
+
171
+ # Run tests
172
+ pytest
173
+
174
+ # Type check with Pyright
175
+ pyright
176
+
177
+ # Lint and format
178
+ ruff check .
179
+ ruff format .
180
+ ```
181
+
182
+ ### Building Distribution
183
+
184
+ **Using uv:**
185
+ ```bash
186
+ # Build wheel and sdist
187
+ uv build
188
+
189
+ # Install locally from wheel
190
+ uv pip install dist/dialectus_engine-*.whl
191
+ ```
192
+
193
+ **Using pip:**
194
+ ```bash
195
+ # Build wheel and sdist
196
+ python -m build
197
+
198
+ # Install locally
199
+ pip install dist/dialectus_engine-*.whl
200
+ ```
201
+
202
+ ### Managing Dependencies
203
+
204
+ **Using uv:**
205
+ ```bash
206
+ # Add a new dependency
207
+ # 1. Edit pyproject.toml [project.dependencies] section
208
+ # 2. Update lock file and sync environment:
209
+ uv lock && uv sync
210
+
211
+ # Upgrade all dependencies (within version constraints)
212
+ uv lock --upgrade
213
+
214
+ # Upgrade specific package
215
+ uv lock --upgrade-package httpx
216
+
217
+ # Add dev dependency
218
+ # 1. Edit pyproject.toml [project.optional-dependencies.dev]
219
+ # 2. Run:
220
+ uv sync
221
+ ```
222
+
223
+ **Using pip:**
224
+ ```bash
225
+ # Add a new dependency
226
+ # 1. Edit pyproject.toml dependencies
227
+ # 2. Reinstall:
228
+ pip install -e ".[dev]"
229
+ ```
230
+
231
+ ### Why uv?
232
+
233
+ - **10-100x faster** than pip for installs and resolution
234
+ - **Reproducible builds** via `uv.lock` (cross-platform, includes hashes)
235
+ - **Python 3.14 ready** - Takes advantage of free-threading for even better performance
236
+ - **Single source of truth** - Dependencies in `pyproject.toml`, lock file auto-generated
237
+ - **Compatible** - `pip` still works perfectly with `pyproject.toml`
238
+
113
239
  ## Features
114
240
 
115
241
  ### Multi-Provider Model Support
@@ -131,6 +257,12 @@ For detailed configuration documentation, see [CONFIG_GUIDE.md](CONFIG_GUIDE.md)
131
257
  - **Structured decisions**: JSON-serializable judge results
132
258
  - **Configurable criteria**: Logic, evidence, persuasiveness, etc.
133
259
 
260
+ ### Content Moderation (Optional)
261
+ - **Multi-provider support**: Ollama (local), OpenRouter, OpenAI moderation API
262
+ - **Safety categories**: Harassment, hate speech, violence, sexual content, dangerous activities
263
+ - **Flexible deployment**: Enable for production APIs, disable for trusted environments
264
+ - **Graceful error handling**: Provider-specific rate limit handling and retry logic
265
+
134
266
  ## Architecture
135
267
 
136
268
  Key architectural principles:
@@ -187,3 +319,26 @@ judge = JudgeFactory.create_judge(config.judging, model_manager)
187
319
  # Get aggregated decision
188
320
  decision = await judge.judge_debate(context)
189
321
  ```
322
+
323
+ ### Content Moderation
324
+
325
+ ```python
326
+ from dialectus.engine.moderation import ModerationManager, TopicRejectedError
327
+
328
+ # Create moderation manager
329
+ manager = ModerationManager(config.moderation, config.system)
330
+
331
+ # Validate user-provided topic
332
+ user_topic = "Should AI be regulated?"
333
+
334
+ try:
335
+ result = await manager.moderate_topic(user_topic)
336
+ # Topic is safe, proceed with debate
337
+ print(f"Topic approved with confidence: {result.confidence}")
338
+ except TopicRejectedError as e:
339
+ # Topic violates content policy
340
+ print(f"Topic rejected: {e.reason}")
341
+ print(f"Violated categories: {', '.join(e.categories)}")
342
+ ```
343
+
344
+ For comprehensive moderation testing and setup instructions, see [MODERATION_TESTING.md](MODERATION_TESTING.md).
@@ -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.1.2"
7
+ __version__ = "0.2.1"
@@ -0,0 +1 @@
1
+ """Configuration management for the AI debate system."""
@@ -11,7 +11,9 @@ class ModelConfig(BaseModel):
11
11
 
12
12
  name: str = Field(
13
13
  ...,
14
- description="Model name (e.g., 'llama3.2:3b' for Ollama, 'openai/gpt-4' for OpenRouter)",
14
+ description=(
15
+ "Model name (e.g., 'llama3.2:3b' for Ollama, 'openai/gpt-4' for OpenRouter)"
16
+ ),
15
17
  )
16
18
  provider: str = Field(
17
19
  default="ollama", description="Model provider (ollama, openrouter, etc.)"
@@ -52,6 +54,52 @@ class JudgingConfig(BaseModel):
52
54
  )
53
55
 
54
56
 
57
+ class ModerationConfig(BaseModel):
58
+ """Content moderation configuration."""
59
+
60
+ enabled: bool = Field(
61
+ default=False, description="Enable content moderation for user topics"
62
+ )
63
+ provider: str = Field(
64
+ default="ollama",
65
+ description=(
66
+ "Moderation provider (ollama, openrouter, openai, or custom). "
67
+ "All providers use OpenAI-compatible endpoints."
68
+ ),
69
+ )
70
+ model: str = Field(
71
+ default="your-moderation-model",
72
+ description=(
73
+ "Model to use for moderation (e.g., 'omni-moderation-latest' for OpenAI "
74
+ "or an instruction-following LLM name for other providers)"
75
+ ),
76
+ )
77
+ base_url: str | None = Field(
78
+ default=None,
79
+ description=(
80
+ "Custom API base URL (optional). "
81
+ "Defaults to system ollama_base_url for ollama, "
82
+ "openrouter.base_url for openrouter."
83
+ ),
84
+ )
85
+ api_key: str | None = Field(
86
+ default=None,
87
+ description=(
88
+ "API key for moderation provider (optional, required for openrouter). "
89
+ "Can use system.openrouter.api_key as fallback."
90
+ ),
91
+ )
92
+ timeout: float = Field(default=10.0, description="Request timeout in seconds", gt=0)
93
+
94
+ @field_validator("provider")
95
+ @classmethod
96
+ def validate_provider(cls, v: str):
97
+ # Provider names are case-insensitive
98
+ # Ollama and openrouter have automatic URL/key resolution
99
+ # Custom providers require explicit base_url
100
+ return v.lower()
101
+
102
+
55
103
  class OllamaConfig(BaseModel):
56
104
  """Ollama-specific configuration for hardware optimization."""
57
105
 
@@ -70,7 +118,10 @@ class OllamaConfig(BaseModel):
70
118
  )
71
119
  keep_alive: str | None = Field(
72
120
  default="5m",
73
- description="How long to keep models loaded (e.g., '5m', '1h', '0' for immediate unload)",
121
+ description=(
122
+ "How long to keep models loaded (e.g., '5m', '1h', '0' for immediate"
123
+ " unload)"
124
+ ),
74
125
  )
75
126
  repeat_penalty: float | None = Field(
76
127
  default=1.1, description="Penalty for repetition in responses"
@@ -82,7 +133,9 @@ class OpenRouterConfig(BaseModel):
82
133
 
83
134
  api_key: str | None = Field(
84
135
  default=None,
85
- description="OpenRouter API key (can also be set via OPENROUTER_API_KEY env var)",
136
+ description=(
137
+ "OpenRouter API key (can also be set via OPENROUTER_API_KEY env var)"
138
+ ),
86
139
  )
87
140
  base_url: str = Field(
88
141
  default="https://openrouter.ai/api/v1", description="OpenRouter API base URL"
@@ -143,6 +196,9 @@ class AppConfig(BaseModel):
143
196
  debate: DebateConfig
144
197
  models: dict[str, ModelConfig]
145
198
  judging: JudgingConfig
199
+ moderation: ModerationConfig = Field(
200
+ default_factory=ModerationConfig, description="Content moderation settings"
201
+ )
146
202
  system: SystemConfig
147
203
 
148
204
  @classmethod
@@ -197,7 +253,9 @@ def get_template_config() -> AppConfig:
197
253
  """Get template configuration for config file generation."""
198
254
  return AppConfig(
199
255
  debate=DebateConfig(
200
- topic="Should artificial intelligence be regulated by government oversight?",
256
+ topic=(
257
+ "Should artificial intelligence be regulated by government oversight?"
258
+ ),
201
259
  format="oxford",
202
260
  time_per_turn=120,
203
261
  word_limit=100,
@@ -234,7 +292,9 @@ def get_template_config() -> AppConfig:
234
292
  repeat_penalty=1.1,
235
293
  ),
236
294
  openrouter=OpenRouterConfig(
237
- api_key=None, # Set your OpenRouter API key here or use OPENROUTER_API_KEY env var
295
+ # Set your OpenRouter API key here or use
296
+ # OPENROUTER_API_KEY env var
297
+ api_key=None,
238
298
  base_url="https://openrouter.ai/api/v1",
239
299
  site_url=None, # Your site URL for referrer tracking (optional)
240
300
  app_name="Dialectus AI Debate System",
@@ -21,4 +21,4 @@ __all__ = [
21
21
  "ResponseHandler",
22
22
  "RoundManager",
23
23
  "JudgeCoordinator",
24
- ]
24
+ ]