{"id":"c2ac915e-1887-4640-8336-6c9be5962e4c","shortId":"mtTKCM","kind":"skill","title":"dspy-optimize-anything","tagline":"Universal text artifact optimizer using GEPA's optimize_anything API for code, prompts, agent architectures, configs, and more","description":"# GEPA optimize_anything\n\n## Goal\n\nOptimize any artifact representable as text — code, prompts, agent architectures, vector graphics, configurations — using a single declarative API powered by GEPA's reflective evolutionary search.\n\n## When to Use\n\n- **Beyond prompt optimization** — optimizing code, configs, SVGs, scheduling policies, etc.\n- **Single hard problems** — circle packing, kernel generation, algorithm discovery\n- **Batch related problems** — CUDA kernels, code generation tasks with cross-transfer\n- **Generalization** — agent skills, policies, or prompts that must transfer to unseen inputs\n- When you can **express quality as a score** and provide **diagnostic feedback** (ASI)\n\n## Inputs\n\n| Input | Type | Description |\n|-------|------|-------------|\n| `seed_candidate` | `str \\| dict[str, str] \\| None` | Starting artifact text, or `None` for seedless mode |\n| `evaluator` | `Callable` | Returns score (higher=better), optionally with ASI dict |\n| `dataset` | `list \\| None` | Training examples (for multi-task and generalization modes) |\n| `valset` | `list \\| None` | Validation set (for generalization mode) |\n| `objective` | `str \\| None` | Natural language description of what to optimize for |\n| `background` | `str \\| None` | Domain knowledge and constraints |\n| `config` | `GEPAConfig \\| None` | Engine, reflection, and tracking settings |\n\n## Outputs\n\n| Output | Type | Description |\n|--------|------|-------------|\n| `result.best_candidate` | `str \\| dict` | Best optimized artifact |\n\n## Workflow\n\n### Phase 1: Install\n\n```bash\npip install gepa\n```\n\n### Phase 2: Define Evaluator with ASI\n\nThe evaluator scores a candidate and returns Actionable Side Information (ASI) — diagnostic feedback that guides the LLM proposer during reflection.\n\n**Simple evaluator (score only):**\n\n```python\nimport gepa.optimize_anything as oa\n\ndef evaluate(candidate: str) -> float:\n    score, diagnostic = run_my_system(candidate)\n    oa.log(f\"Error: {diagnostic}\")  # captured as ASI\n    return score\n```\n\n**Rich evaluator (score + structured ASI):**\n\n```python\ndef evaluate(candidate: str) -> tuple[float, dict]:\n    result = execute_code(candidate)\n    return result.score, {\n        \"Error\": result.stderr,\n        \"Output\": result.stdout,\n        \"Runtime\": f\"{result.time_ms:.1f}ms\",\n    }\n```\n\nASI can include open-ended text, structured data, multi-objectives (via `scores`), or images (via `gepa.Image`) for vision-capable LLMs.\n\n### Phase 3: Choose Optimization Mode\n\n**Mode 1 — Single-Task Search:** Solve one hard problem. No dataset needed.\n\n```python\nresult = oa.optimize_anything(\n    seed_candidate=\"<your initial artifact>\",\n    evaluator=evaluate,\n)\n```\n\n**Mode 2 — Multi-Task Search:** Solve a batch of related problems with cross-transfer.\n\n```python\nresult = oa.optimize_anything(\n    seed_candidate=\"<your initial artifact>\",\n    evaluator=evaluate,\n    dataset=tasks,\n)\n```\n\n**Mode 3 — Generalization:** Build a skill/prompt/policy that transfers to unseen problems.\n\n```python\nresult = oa.optimize_anything(\n    seed_candidate=\"<your initial artifact>\",\n    evaluator=evaluate,\n    dataset=train,\n    valset=val,\n)\n```\n\n**Seedless mode:** Describe what you need instead of providing a seed.\n\n```python\nresult = oa.optimize_anything(\n    evaluator=evaluate,\n    objective=\"Generate a Python function `reverse()` that reverses a string.\",\n)\n```\n\n### Phase 4: Use Results\n\n```python\nprint(result.best_candidate)\n```\n\n## Production Example\n\n```python\nimport gepa.optimize_anything as oa\nfrom gepa import Image\nimport logging\n\nlogger = logging.getLogger(__name__)\n\n# ---------- SVG optimization with VLM feedback ----------\n\nGOAL = \"a pelican riding a bicycle\"\nVLM = \"vertex_ai/gemini-3-flash-preview\"\n\nVISUAL_ASPECTS = [\n    {\"id\": \"overall\",     \"criteria\": f\"Rate overall quality of this SVG ({GOAL}). SCORE: X/10\"},\n    {\"id\": \"anatomy\",     \"criteria\": \"Rate pelican accuracy: beak, pouch, plumage. SCORE: X/10\"},\n    {\"id\": \"bicycle\",     \"criteria\": \"Rate bicycle: wheels, frame, handlebars, pedals. SCORE: X/10\"},\n    {\"id\": \"composition\", \"criteria\": \"Rate how convincingly the pelican rides the bicycle. SCORE: X/10\"},\n]\n\ndef evaluate(candidate, example):\n    \"\"\"Render SVG, score with a VLM, return (score, ASI).\"\"\"\n    image = render_image(candidate[\"svg_code\"])  # via cairosvg\n    score, feedback = get_vlm_score_feedback(VLM, image, example[\"criteria\"])\n\n    return score, {\n        \"RenderedSVG\": Image(base64_data=image, media_type=\"image/png\"),\n        \"Feedback\": feedback,\n    }\n\nresult = oa.optimize_anything(\n    seed_candidate={\"svg_code\": \"<svg>...</svg>\"},\n    evaluator=evaluate,\n    dataset=VISUAL_ASPECTS,\n    background=f\"Optimize SVG source code depicting '{GOAL}'. \"\n               \"Improve anatomy, composition, and visual quality.\",\n)\n\nlogger.info(f\"Best SVG:\\n{result.best_candidate['svg_code']}\")\n\n\n# ---------- Code optimization (single-task) ----------\n\ndef evaluate_solver(candidate: str) -> tuple[float, dict]:\n    \"\"\"Evaluate a Python solver for a mathematical optimization problem.\"\"\"\n    import subprocess, json\n\n    proc = subprocess.run(\n        [\"python\", \"-c\", candidate],\n        capture_output=True, text=True, timeout=30,\n    )\n\n    if proc.returncode != 0:\n        oa.log(f\"Runtime error: {proc.stderr}\")\n        return 0.0, {\"Error\": proc.stderr}\n\n    try:\n        output = json.loads(proc.stdout)\n        return output[\"score\"], {\n            \"Output\": output.get(\"solution\"),\n            \"Runtime\": f\"{output.get('time_ms', 0):.1f}ms\",\n        }\n    except (json.JSONDecodeError, KeyError) as e:\n        oa.log(f\"Parse error: {e}\")\n        return 0.0, {\"Error\": str(e), \"Stdout\": proc.stdout}\n\nresult = oa.optimize_anything(\n    evaluator=evaluate_solver,\n    objective=\"Write a Python solver for the bin packing problem that \"\n              \"minimizes the number of bins. Output JSON with 'score' and 'solution'.\",\n    background=\"Use first-fit-decreasing as a starting heuristic. \"\n               \"Higher score = fewer bins used.\",\n)\n\nprint(result.best_candidate)\n\n\n# ---------- Agent architecture generalization ----------\n\ndef evaluate_agent(candidate: str, example: dict) -> tuple[float, dict]:\n    \"\"\"Run an agent architecture on a task and score it.\"\"\"\n    exec_globals = {}\n    exec(candidate, exec_globals)\n    agent_fn = exec_globals.get(\"solve\")\n\n    if agent_fn is None:\n        return 0.0, {\"Error\": \"No `solve` function defined\"}\n\n    try:\n        prediction = agent_fn(example[\"input\"])\n        correct = prediction == example[\"expected\"]\n        score = 1.0 if correct else 0.0\n        feedback = \"Correct\" if correct else (\n            f\"Expected '{example['expected']}', got '{prediction}'\"\n        )\n        return score, {\"Prediction\": prediction, \"Feedback\": feedback}\n    except Exception as e:\n        return 0.0, {\"Error\": str(e)}\n\nresult = oa.optimize_anything(\n    seed_candidate=\"def solve(input):\\n    return input\",\n    evaluator=evaluate_agent,\n    dataset=train_tasks,\n    valset=val_tasks,\n    background=\"Discover a Python agent function `solve(input)` that \"\n               \"generalizes across unseen reasoning tasks.\",\n)\n\nprint(result.best_candidate)\n```\n\n## Integration with DSPy\n\n`optimize_anything` complements DSPy's built-in optimizers. Use DSPy optimizers (GEPA, MIPROv2, BootstrapFewShot) for DSPy programs, and `optimize_anything` for arbitrary text artifacts outside DSPy:\n\n```python\nimport dspy\nimport gepa.optimize_anything as oa\n\n# DSPy program optimization (use dspy.GEPA)\noptimizer = dspy.GEPA(\n    metric=gepa_metric,\n    reflection_lm=dspy.LM(\"openai/gpt-4o\"),\n    auto=\"medium\",\n)\ncompiled = optimizer.compile(agent, trainset=trainset)\n\n# Non-DSPy artifact optimization (use optimize_anything)\nresult = oa.optimize_anything(\n    seed_candidate=my_config_yaml,\n    evaluator=eval_config,\n    background=\"Optimize Kubernetes scheduling policy for cost.\",\n)\n```\n\n## Best Practices\n\n1. **Rich ASI** — The more diagnostic feedback you provide, the better the proposer can reason about improvements\n2. **Use `oa.log()`** — Route prints to the proposer as ASI instead of stdout\n3. **Structured returns** — Return `(score, dict)` tuples for multi-faceted diagnostics\n4. **Seedless for exploration** — Use `objective=` when the solution space is large and unfamiliar\n5. **Background context** — Provide domain knowledge via `background=` to constrain the search\n6. **Generalization mode** — Always provide `valset` when the artifact must transfer to unseen inputs\n7. **Images as ASI** — Use `gepa.Image` to pass rendered outputs to vision-capable LLMs\n\n## Limitations\n\n- Requires the `gepa` package (`pip install gepa`)\n- Evaluator must be deterministic or low-variance for stable optimization\n- Compute cost scales with number of candidates explored\n- Single-task mode does not generalize; use mode 3 with `valset` for transfer\n- Currently powered by GEPA backend; API is backend-agnostic for future strategies","tags":["dspy","optimize","anything","skills","omidzamani","agent-skills","claude-code","claude-skills","llm","prompt-optimization","rag"],"capabilities":["skill","source-omidzamani","skill-dspy-optimize-anything","topic-agent-skills","topic-claude-code","topic-claude-skills","topic-dspy","topic-llm","topic-prompt-optimization","topic-rag"],"categories":["dspy-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/OmidZamani/dspy-skills/dspy-optimize-anything","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add OmidZamani/dspy-skills","source_repo":"https://github.com/OmidZamani/dspy-skills","install_from":"skills.sh"}},"qualityScore":"0.487","qualityRationale":"deterministic score 0.49 from registry signals: · indexed on github topic:agent-skills · 74 github stars · SKILL.md body (8,935 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T06:55:44.564Z","embedding":null,"createdAt":"2026-04-18T22:14:14.966Z","updatedAt":"2026-05-02T06:55:44.564Z","lastSeenAt":"2026-05-02T06:55:44.564Z","tsv":"'0':621,646 '0.0':628,660,751,772,795 '1':199,319,923 '1.0':768 '1f':288,647 '2':206,340,940 '3':314,366,953,1056 '30':618 '4':416,965 '5':979 '6':991 '7':1005 'accuraci':474 'across':829 'action':218 'agent':18,35,87,712,717,727,741,746,759,812,823,892 'agnost':1070 'ai/gemini-3-flash-preview':453 'algorithm':72 'alway':994 'anatomi':470,568 'anyth':4,13,25,238,334,358,379,402,428,549,668,801,840,859,871,902,905 'api':14,44,1066 'arbitrari':861 'architectur':19,36,713,728 'artifact':7,29,123,196,863,898,999 'asi':110,138,210,221,258,265,290,516,925,949,1008 'aspect':455,558 'auto':888 'backend':1065,1069 'backend-agnost':1068 'background':171,559,694,819,914,980,986 'base64':539 'bash':201 'batch':74,347 'beak':475 'best':194,575,921 'better':135,933 'beyond':55 'bicycl':450,481,484,501 'bin':679,687,707 'bootstrapfewshot':853 'build':368 'built':845 'built-in':844 'c':610 'cairosvg':524 'callabl':131 'candid':116,191,215,243,251,269,277,336,360,381,422,506,520,551,579,590,611,711,718,738,803,835,907,1045 'capabl':311,1018 'captur':256,612 'choos':315 'circl':68 'code':16,33,59,79,276,522,553,564,581,582 'compil':890 'complement':841 'composit':492,569 'comput':1039 'config':20,60,178,909,913 'configur':39 'constrain':988 'constraint':177 'context':981 'convinc':496 'correct':763,770,774,776 'cost':920,1040 'criteria':458,471,482,493,534 'cross':84,353 'cross-transf':83,352 'cuda':77 'current':1061 'data':298,540 'dataset':140,329,363,384,556,813 'declar':43 'decreas':699 'def':241,267,504,587,715,804 'defin':207,756 'depict':565 'describ':390 'descript':114,165,189 'determinist':1031 'diagnost':108,222,247,255,928,964 'dict':118,139,193,273,594,721,724,958 'discov':820 'discoveri':73 'domain':174,983 'dspi':2,838,842,849,855,865,868,874,897 'dspy-optimize-anyth':1 'dspy.gepa':878,880 'dspy.lm':886 'e':653,658,663,793,798 'els':771,777 'end':295 'engin':181 'error':254,280,625,629,657,661,752,796 'etc':64 'eval':912 'evalu':130,208,212,232,242,262,268,337,338,361,362,382,383,403,404,505,554,555,588,595,669,670,716,810,811,911,1028 'evolutionari':50 'exampl':144,424,507,533,720,761,765,780 'except':649,790,791 'exec':735,737,739 'exec_globals.get':743 'execut':275 'expect':766,779,781 'explor':968,1046 'express':101 'f':253,285,459,560,574,623,642,655,778 'facet':963 'feedback':109,223,444,526,530,545,546,773,788,789,929 'fewer':706 'first':697 'first-fit-decreas':696 'fit':698 'float':245,272,593,723 'fn':742,747,760 'frame':486 'function':409,755,824 'futur':1072 'general':86,150,158,367,714,828,992,1053 'generat':71,80,406 'gepa':10,23,47,204,432,851,882,1023,1027,1064 'gepa.image':307,1010 'gepa.optimize':237,427,870 'gepaconfig':179 'get':527 'global':736,740 'goal':26,445,466,566 'got':782 'graphic':38 'guid':225 'handlebar':487 'hard':66,326 'heurist':703 'higher':134,704 'id':456,469,480,491 'imag':305,434,517,519,532,538,541,1006 'image/png':544 'import':236,426,433,435,604,867,869 'improv':567,939 'includ':292 'inform':220 'input':97,111,112,762,806,809,826,1004 'instal':200,203,1026 'instead':394,950 'integr':836 'json':606,689 'json.jsondecodeerror':650 'json.loads':633 'kernel':70,78 'keyerror':651 'knowledg':175,984 'kubernet':916 'languag':164 'larg':976 'limit':1020 'list':141,153 'llm':227 'llms':312,1019 'lm':885 'log':436 'logger':437 'logger.info':573 'logging.getlogger':438 'low':1034 'low-vari':1033 'mathemat':601 'media':542 'medium':889 'metric':881,883 'minim':683 'miprov2':852 'mode':129,151,159,317,318,339,365,389,993,1050,1055 'ms':287,289,645,648 'multi':147,300,342,962 'multi-facet':961 'multi-object':299 'multi-task':146,341 'must':93,1000,1029 'n':577,807 'name':439 'natur':163 'need':330,393 'non':896 'non-dspi':895 'none':121,126,142,154,162,173,180,749 'number':685,1043 'oa':240,430,873 'oa.log':252,622,654,942 'oa.optimize':333,357,378,401,548,667,800,904 'object':160,301,405,672,970 'one':325 'open':294 'open-end':293 'openai/gpt-4o':887 'optim':3,8,12,24,27,57,58,169,195,316,441,561,583,602,839,847,850,858,876,879,899,901,915,1038 'optimizer.compile':891 'option':136 'output':186,187,282,613,632,636,638,688,1014 'output.get':639,643 'outsid':864 'overal':457,461 'pack':69,680 'packag':1024 'pars':656 'pass':1012 'pedal':488 'pelican':447,473,498 'phase':198,205,313,415 'pip':202,1025 'plumag':477 'polici':63,89,918 'pouch':476 'power':45,1062 'practic':922 'predict':758,764,783,786,787 'print':420,709,833,944 'problem':67,76,327,350,375,603,681 'proc':607 'proc.returncode':620 'proc.stderr':626,630 'proc.stdout':634,665 'product':423 'program':856,875 'prompt':17,34,56,91 'propos':228,935,947 'provid':107,396,931,982,995 'python':235,266,331,355,376,399,408,419,425,597,609,675,822,866 'qualiti':102,462,572 'rate':460,472,483,494 'reason':831,937 'reflect':49,182,230,884 'relat':75,349 'render':508,518,1013 'renderedsvg':537 'represent':30 'requir':1021 'result':274,332,356,377,400,418,547,666,799,903 'result.best':190,421,578,710,834 'result.score':279 'result.stderr':281 'result.stdout':283 'result.time':286 'return':132,217,259,278,514,535,627,635,659,750,784,794,808,955,956 'revers':410,412 'rich':261,924 'ride':448,499 'rout':943 'run':248,725 'runtim':284,624,641 'scale':1041 'schedul':62,917 'score':105,133,213,233,246,260,263,303,467,478,489,502,510,515,525,529,536,637,691,705,733,767,785,957 'search':51,323,344,990 'seed':115,335,359,380,398,550,802,906 'seedless':128,388,966 'set':156,185 'side':219 'simpl':231 'singl':42,65,321,585,1048 'single-task':320,584,1047 'skill':88 'skill-dspy-optimize-anything' 'skill/prompt/policy':370 'solut':640,693,973 'solv':324,345,744,754,805,825 'solver':589,598,671,676 'sourc':563 'source-omidzamani' 'space':974 'stabl':1037 'start':122,702 'stdout':664,952 'str':117,119,120,161,172,192,244,270,591,662,719,797 'strategi':1073 'string':414 'structur':264,297,954 'subprocess':605 'subprocess.run':608 'svg':440,465,509,521,552,562,576,580 'svgs':61 'system':250 'task':81,148,322,343,364,586,731,815,818,832,1049 'text':6,32,124,296,615,862 'time':644 'timeout':617 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-dspy' 'topic-llm' 'topic-prompt-optimization' 'topic-rag' 'track':184 'train':143,385,814 'trainset':893,894 'transfer':85,94,354,372,1001,1060 'tri':631,757 'true':614,616 'tupl':271,592,722,959 'type':113,188,543 'unfamiliar':978 'univers':5 'unseen':96,374,830,1003 'use':9,40,54,417,695,708,848,877,900,941,969,1009,1054 'val':387,817 'valid':155 'valset':152,386,816,996,1058 'varianc':1035 'vector':37 'vertex':452 'via':302,306,523,985 'vision':310,1017 'vision-cap':309,1016 'visual':454,557,571 'vlm':443,451,513,528,531 'wheel':485 'workflow':197 'write':673 'x/10':468,479,490,503 'yaml':910","prices":[{"id":"2962e43b-2436-4d4e-ab47-ad8ef04a86f5","listingId":"c2ac915e-1887-4640-8336-6c9be5962e4c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"OmidZamani","category":"dspy-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:14:14.966Z"}],"sources":[{"listingId":"c2ac915e-1887-4640-8336-6c9be5962e4c","source":"github","sourceId":"OmidZamani/dspy-skills/dspy-optimize-anything","sourceUrl":"https://github.com/OmidZamani/dspy-skills/tree/master/skills/dspy-optimize-anything","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:14.966Z","lastSeenAt":"2026-05-02T06:55:44.564Z"}],"details":{"listingId":"c2ac915e-1887-4640-8336-6c9be5962e4c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"OmidZamani","slug":"dspy-optimize-anything","github":{"repo":"OmidZamani/dspy-skills","stars":74,"topics":["agent-skills","claude-code","claude-skills","dspy","llm","prompt-optimization","rag"],"license":"mit","html_url":"https://github.com/OmidZamani/dspy-skills","pushed_at":"2026-02-21T12:49:43Z","description":"Collection of Claude Skills for DSPy framework - program language models, optimize prompts, and build RAG pipelines systematically","skill_md_sha":"0b377d887ff2af0ee9803596c291fc6f84a08cb0","skill_md_path":"skills/dspy-optimize-anything/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/OmidZamani/dspy-skills/tree/master/skills/dspy-optimize-anything"},"layout":"multi","source":"github","category":"dspy-skills","frontmatter":{"name":"dspy-optimize-anything","description":"Universal text artifact optimizer using GEPA's optimize_anything API for code, prompts, agent architectures, configs, and more"},"skills_sh_url":"https://skills.sh/OmidZamani/dspy-skills/dspy-optimize-anything"},"updatedAt":"2026-05-02T06:55:44.564Z"}}