Feat/optimizer microservice

Dockerfile

@@ -35,3 +35,5 @@ COPY --from=builder /wheels /wheels
 
 # Install the application wheel
 RUN pip install --no-cache-dir /wheels/*.whl
+
+CMD ["uvicorn", "coreason_optimizer.server:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -20,6 +20,7 @@ pip install coreason-optimizer
 ## Features
 
 -   **Automated Optimization:** Rewrites instructions and selects examples to maximize a score, not human intuition.
+-   **Optimization-as-a-Service:** Run as a microservice API to compile prompts on-demand.
 -   **Model-Specific Compilation:** Generates optimized prompts specifically tuned for target models (e.g., GPT-4, Claude 3.5).
 -   **Continuous Learning:** Re-runs optimization on recent logs to patch prompts against data drift.
 -   **Mutate-Evaluate Loop:** Systematic cycle of drafting, evaluating, diagnosing, mutating, and selecting prompts.
@@ -30,40 +31,44 @@ For full product requirements, see [docs/product_requirements.md](docs/product_r
 
 ## Usage
 
-Here is how to initialize and use the library to compile an agent:
+You can use `coreason-optimizer` as a Python library, a CLI tool, or a Microservice.
+
+### 1. Python Library
 
 ```python
 from coreason_optimizer import OptimizerConfig, PromptOptimizer
 from coreason_optimizer.core.interfaces import Construct
 from coreason_optimizer.data import Dataset
 
-# 1. Configuration
-config = OptimizerConfig(
-    target_model="gpt-4o",
-    metric="exact_match",
-    max_rounds=10
-)
-
-# 2. Load Data
-dataset = Dataset.from_csv("data/gold_set.csv")
-train_set, val_set = dataset.split(test_size=0.2)
-
-# 3. Load Agent (Construct)
-# In a real scenario, this would be imported from your agent code
-# from src.agents.analyst import analyst_agent
+# Define Agent
 class MockAgent(Construct):
     inputs = ["question"]
     outputs = ["answer"]
     system_prompt = "You are a helpful assistant."
 agent = MockAgent()
 
-# 4. Compile
-optimizer = PromptOptimizer(config=config)
-optimized_manifest = optimizer.compile(
-    agent=agent,
-    trainset=train_set,
-    valset=val_set
-)
+# Compile
+dataset = Dataset.from_csv("data/gold_set.csv")
+train_set, val_set = dataset.split(train_ratio=0.8)
+
+optimizer = PromptOptimizer(config=OptimizerConfig(target_model="gpt-4o"))
+manifest = optimizer.compile(agent, train_set, val_set)
+
+print(f"Optimized Score: {manifest.performance_metric}")
+```
+
+### 2. Server Mode (Microservice)
+
+Run the optimizer as a standalone service using Docker:
+
+```bash
+docker run -p 8000:8000 -e OPENAI_API_KEY=$OPENAI_API_KEY coreason-optimizer:latest
+```
+
+Then call the API:
+
+```bash
+curl -X POST http://localhost:8000/optimize -d @request.json
+```
 
-print(f"Optimization complete. New Score: {optimized_manifest.performance_metric}")
-print(f"Optimized Instruction: {optimized_manifest.optimized_instruction}")
+For detailed instructions, see **[docs/usage.md](docs/usage.md)**.

docs/requirements.md

@@ -0,0 +1,35 @@
+# Requirements
+
+## Runtime Dependencies
+
+The following packages are required for `coreason-optimizer` to function:
+
+*   `python >= 3.12`
+*   `click >= 8.0.0`
+*   `jinja2 >= 3.0.0`
+*   `loguru >= 0.6.0`
+*   `numpy >= 1.20.0`
+*   `openai >= 1.0.0`
+*   `pydantic >= 2.0.0`
+*   `scikit-learn >= 1.0.0`
+*   `coreason-identity >= 0.4.1`
+
+### Server Mode (Microservice)
+
+For running the optimization microservice (Server Mode), the following additional dependencies are required:
+
+*   `fastapi >= 0.100.0`
+*   `uvicorn >= 0.20.0`
+*   `httpx`
+*   `anyio`
+
+## Development Dependencies
+
+For development and testing:
+
+*   `pytest`
+*   `ruff`
+*   `pre-commit`
+*   `pytest-cov`
+*   `mkdocs`
+*   `mkdocs-material`

docs/usage.md

@@ -0,0 +1,130 @@
+# Usage Guide
+
+`coreason-optimizer` offers three ways to compile and optimize agents:
+1.  **Python Library:** Integrate directly into your Python code.
+2.  **CLI:** Use the command-line tool for scripts and CI/CD.
+3.  **Server Mode (Microservice):** Run as a standalone API service.
+
+---
+
+## 1. Python Library
+
+Use the library to programmatically compile agents.
+
+```python
+from coreason_optimizer import OptimizerConfig, PromptOptimizer
+from coreason_optimizer.core.interfaces import Construct
+from coreason_optimizer.data import Dataset
+
+# 1. Define your Agent
+class MyAgent(Construct):
+    inputs = ["user_query"]
+    outputs = ["response", "thought_trace"]
+    system_prompt = "You are a helpful AI assistant."
+
+agent = MyAgent()
+
+# 2. Load Data
+dataset = Dataset.from_csv("data/training_data.csv")
+train_set, val_set = dataset.split(train_ratio=0.8)
+
+# 3. Configure Optimizer
+config = OptimizerConfig(
+    target_model="gpt-4o",
+    metric="exact_match",
+    budget_limit_usd=5.0
+)
+
+# 4. Compile
+optimizer = PromptOptimizer(config=config)
+manifest = optimizer.compile(agent, train_set, val_set)
+
+print(f"Optimization Score: {manifest.performance_metric}")
+```
+
+---
+
+## 2. Command Line Interface (CLI)
+
+The `coreason-opt` CLI allows you to run optimization jobs from the shell.
+
+### Tune an Agent
+
+```bash
+coreason-opt tune \
+    --agent src/agents/analyst.py \
+    --dataset data/gold_set.csv \
+    --strategy mipro \
+    --output optimized_analyst.json
+```
+
+### Evaluate a Manifest
+
+```bash
+coreason-opt evaluate \
+    --manifest optimized_analyst.json \
+    --dataset data/test_set.csv
+```
+
+---
+
+## 3. Server Mode (Optimization-as-a-Service)
+
+You can run `coreason-optimizer` as a containerized microservice that accepts optimization requests via HTTP.
+
+### Starting the Server
+
+**Using Docker:**
+
+```bash
+docker build -t coreason-optimizer:latest .
+docker run -p 8000:8000 -e OPENAI_API_KEY=sk-... coreason-optimizer:latest
+```
+
+**Using Uvicorn (Locally):**
+
+```bash
+uvicorn coreason_optimizer.server:app --host 0.0.0.0 --port 8000
+```
+
+### API Endpoints
+
+#### `POST /optimize`
+
+Submits an optimization job.
+
+**Request Body (JSON):**
+
+```json
+{
+  "agent": {
+    "system_prompt": "You are a specialized medical analyst...",
+    "inputs": ["patient_notes"],
+    "outputs": ["diagnosis_code"]
+  },
+  "dataset": [
+    {
+      "inputs": {"patient_notes": "Patient complains of..."},
+      "reference": "E11.9",
+      "metadata": {"source": "manual_review"}
+    },
+    ...
+  ],
+  "config": {
+    "target_model": "gpt-4o",
+    "metric": "exact_match",
+    "budget_limit_usd": 10.0
+  },
+  "strategy": "mipro"
+}
+```
+
+**Response:**
+
+Returns an `OptimizedManifest` JSON object containing the optimized instruction and selected few-shot examples.
+
+#### `GET /health`
+
+Checks service health.
+
+**Response:** `{"status": "ready"}`

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "coreason_optimizer"
-version = "0.2.1"
+version = "0.3.0"
 description = "coreason-optimizer"
 authors = ["Gowtham A Rao <gowtham.rao@coreason.ai>"]
 license = "Prosperity-3.0"
@@ -21,6 +21,8 @@ httpx = "^0.28.1"
 aiofiles = "*"
 types-aiofiles = "*"
 coreason-identity = "^0.4.1"
+fastapi = "^0.128.0"
+uvicorn = "^0.40.0"
 
 [tool.poetry.scripts]
 coreason-opt = "coreason_optimizer.main:cli"

requirements.txt

@@ -5,3 +5,5 @@ numpy>=1.20.0
 openai>=1.0.0
 pydantic>=2.0.0
 scikit-learn>=1.0.0
+fastapi>=0.100.0
+uvicorn>=0.20.0