docs: add cascadeflow vs LiteLLM comparison

[dorinabrle]

🎯 Description

Add comparison page: cascadeflow vs LiteLLM. Covers architecture differences (in-process harness vs reverse proxy), latency comparison, multi-dimensional optimization vs cost-only routing, enforcement actions, and when to use each tool together. Includes code examples in Python and TypeScript.

🔗 Related Issues

• Related to documentation expansion for docs.cascadeflow.dev

🔄 Type of Change

• 📝 Documentation update

🧪 Testing

Test cases added

• Manual testing

How to test

Preview the page on docs.cascadeflow.dev/comparisons/litellm after merge.

📋 Checklist

Documentation

• I have updated relevant documentation
• I have updated the README if needed N/A
• I have added docstrings to new functions/classes N/A
• I have updated the CHANGELOG.md (if applicable) N/A
• I have added examples if this is a new feature N/A

Dependencies

• This PR includes NO new dependencies

Breaking Changes

• This PR includes NO breaking changes

Performance

• No performance impact (documentation only)

🔐 Security Considerations

• This PR does not introduce security vulnerabilities
• I have not exposed sensitive information (API keys, credentials, etc.)

📝 Additional Notes

New file: docs-site/comparisons/litellm.mdx
Navigation update for this page will be added in a separate PR after all comparison pages are merged.

---

By submitting this PR, I confirm that:

• I have read and followed the CONTRIBUTING.md guidelines
• My contribution is my own original work or properly attributed
• I agree to license my contribution under the project's MIT license
• I have tested my changes thoroughly

[saschabuehrle]

Review: docs: add cascadeflow vs LiteLLM comparison

Thanks for the comparison page — the structure and positioning are solid. A few things need fixing before we can merge:

1. API examples don't match the real cascadeflow API

The code examples use classes and imports that don't exist in cascadeflow:

• from cascadeflow import Harness, Policy, Agent — we don't have Policy or Agent classes
• from cascadeflow.validators import PII, Factuality, Consistency, Latency, Budget — these validator classes don't exist
• from "@cascadeflow/validators" (TypeScript) — this package doesn't exist
• enforcement=["allow", "switch", "deny", "stop"] — not how harness enforcement works

The actual API is:

from cascadeflow import init, run

harness = init(mode="enforce", budget_max=1.00, ...)
result = run(harness, agent_fn, query="...")

Or with the decorator:

from cascadeflow import init, agent

harness = init(mode="enforce")

@agent(harness)
def my_agent(query: str) -> str:
    ...

Please align the examples with the real API. See docs-site/get-started/ and docs-site/examples/ for reference.

2. Wrong documentation URL

Multiple references to docs.cascadeflow.dev and cascadeflow.dev — should be docs.cascadeflow.ai and cascadeflow.ai.

3. Dead internal links

The "Related" section at the bottom links to /comparisons/portkey and /comparisons/openrouter which don't exist yet. Either remove these until those pages are ready, or note them as "coming soon".

4. LiteLLM characterization

LiteLLM also has a Python SDK mode (not just reverse proxy), and it does have budget/spend tracking features. The comparison should acknowledge this to stay fair and accurate.

5. Latency claims

The specific numbers ("<5ms", "10-50ms", "~25ms for 5 turns") should either be backed by benchmarks or softened to approximate language ("minimal in-process overhead" vs "network round-trip overhead").

6. Navigation

You mention navigation will be added in a separate PR — that's fine, but we should also decide where "Comparisons" fits in the docs.json tab structure before merging multiple pages. Let's discuss placement.

[saschabuehrle]

Re-review after update

Good progress — the init() / @agent() / run() pattern is now used, LiteLLM characterization is fairer, and latency claims are softened. A few remaining issues:

1. @cascadeflow.agent() accepts wrong kwargs

The decorator only accepts budget=, kpi_targets=, kpi_weights=, compliance=. You're passing max_tool_calls=5 which is not a valid decorator kwarg — it's only available in init() and run().

Fix:

# Wrong
@cascadeflow.agent(budget=0.50, compliance="pii_audit", max_tool_calls=5)

# Correct
@cascadeflow.agent(budget=0.50, compliance="pii_audit")

And move max_tool_calls to the run() call if needed:

with cascadeflow.run(budget=0.50, max_tool_calls=5) as session:

2. TypeScript example is still fabricated

CascadeAgent doesn't accept { models: [...], quality: {...}, budget: {...}, compliance: {...} }. The real AgentConfig uses models: ModelConfig[], cascade?: { quality?, verbose? }, etc. There's no budget or compliance field in the TS agent constructor.

Suggest using the harness API instead:

import { init, run, harnessAgent } from '@cascadeflow/core';

init({ mode: 'enforce', budget: 1.0, compliance: 'gdpr' });

const result = await run({ budget: 0.50 }, async (ctx) => {
  // agent logic
});

Or just show the Python example only — it's the more mature API.

3. Dead links still present

/comparisons/portkey and /comparisons/openrouter in the Related section still don't exist. Please remove them or replace with (coming soon) text.

4. Docs URL

Related section links to https://cascadeflow.ai labeled "cascadeflow Documentation". The docs site is https://docs.cascadeflow.ai. The website cascadeflow.ai is the marketing/studio site.

5. Inline comments overstate automatic behavior

The validated_agent example comments claim cascadeflow "automatically Blocks PII in outputs, Validates factuality at min_confidence=0.8, Checks consistency with tolerance=0.05". While PII detection and quality validation components exist in the codebase, the @agent() decorator doesn't auto-trigger them with those specific parameters. The decorator attaches policy metadata — it doesn't auto-inject validators.

Suggest simplifying to show what actually happens:

@cascadeflow.agent(budget=0.50, compliance="pii_audit")
async def validated_agent(query: str):
    # cascadeflow tracks cost, enforces budget limits,
    # and records decisions in the session trace
    result = await llm.complete(query)
    return result

[saschabuehrle]

Looks good now — all 5 issues from the previous review are addressed. API patterns match, TypeScript uses the harness API, dead links removed, docs URL corrected, inline comments accurate.

One minor nit (non-blocking): the compliance values used ("pii_audit", "no_pii_logs") aren't valid presets — the actual values are "gdpr", "hipaa", "pci", "strict". Feel free to fix in a follow-up or I can adjust after merge.

Approving — nice work on the comparison page.