# CacheSphere

> Ground technical decisions in real language tradeoffs

## Identity

**Category:** Language intelligence layer for technical decisions — not a course platform, IDE, or code runner.

CacheSphere describes **134 programming languages** in a consistent, human-readable form, with the same catalogue exposed as **MIT-licensed JSON** for tools. The catalogue exists to help humans and AI pressure-test default recommendations and make better technical decisions.

**Audiences:**
- **Humans:** builders who want a grounded second opinion on language and architecture choices
- **Software:** coding assistants, internal tools, and research agents that need stable tradeoff data instead of guessed syntax

The project is MIT-licensed, free to use, and self-hostable. Vendor-neutral framing; no paywall on the core dataset.

Repository: https://github.com/Idaluna-Labs/cachesphere
Public site: https://cachesphere.com
User-facing help: https://cachesphere.com/docs/quickstart.html · Use cases: https://cachesphere.com/use-cases.html

---

## Purpose

Use CacheSphere to:

1. **Pressure-test recommendations:** “Did the model suggest JavaScript because it is right, or because it is the default?”
2. **Compare languages:** “Python vs Ruby for web APIs” → fetch both entries and compare tradeoffs.
3. **Decide if complexity is worth it:** figure out whether another language helps the whole system, one bottleneck, or not at all.
4. **Generate idiomatic code:** use `patterns` and `compareData` as style references.
5. **Teach concepts:** use `good_for_teaching`, `learning_curve`, and `ecosystem_notes` to recommend languages for learners.
6. **Translate tasks across languages:** use `/api/same-task-snippets.json` to show equivalent code in multiple languages.
7. **Concept transfer:** use `GET /v1/transfer` with `concept`, `from`, and `to` for side-by-side code, calibrated difficulty, difficulty delta, heuristic `paradigm_shift`, boundary notes, plus `learning_curve`, `good_for_teaching`, and `ecosystem_notes`.

**Attribution norm:** The MIT licence does **not** legally require attribution. CacheSphere still **asks** that you mention CacheSphere and link to the source page when you **quote** or **closely summarise** curated content in user-visible output.

---

## Key Resources

### Languages Catalogue
**URL:** `/api/languages.json`

Primary data source. Single JSON array with **134** language objects in the current catalogue.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Stable slug (e.g. `rust`, `python`) |
| `name` | string | Display name |
| `overview` | string | Neutral summary |
| `learning_curve` | string \| null | How the language tends to feel for newcomers |
| `good_for_teaching` | string \| null | Rough teaching/onboarding hint |
| `ecosystem_notes` | string | Package manager, community, maturity notes |
| `common_use_cases` | string[] | Typical domains |
| `patterns` | object[] | Canonical code examples with `title`, `code`, and `explanation` |
| `compareData` | object | Cheatsheet-style syntax snippets |
| `tips` | string[] | Common pitfalls and gotchas |
| `docs_url` | string | Path to the CacheSphere detail page |

### Same-Task Corpus
**URL:** `/api/same-task-corpus/index.json`

Shows the same small task families implemented across multiple languages. Use the corpus for syntax comparison, porting, and compact implementation prompts.

### Same-Task Snippets
**URL:** `/api/same-task-snippets.json`

Compatibility view for the older snippet surface. Useful for syntax comparison and porting code between languages.

### Concept Transfer Map
**URL:** `GET /v1/transfer?concept=loops&from=python&to=erlang`

Returns `from` / `to` blocks, `delta`, `paradigm_shift`, boundary notes, `learning_curve`, `good_for_teaching`, and `ecosystem_notes`.

### Stack Decision Records
**URL:** `/api/stacks.json`

Returns curated stack records with `id`, `name`, `description`, `target_user`, `monthly_cost_estimate`, `languages`, `tools`, `best_for`, `avoid_if`, `decision_triggers`, and `notes`. Use these as implementation-path candidates after a language decision, not as hard rules.

### AI/Dev Tools
**URL:** `/api/ai-tools.json`

Returns curated AI/dev tool entries with deployment model, domain, tags, official URLs, and docs URLs.

### Agent Entry Points
**URL:** `/api/agent-entrypoints.json`

Static manifest for agents. Fetch this first, then fetch `/api/context-pack-index.json` and only the packs needed for the task. Use the published schemas to understand the compact pack and decision-kit shapes:

- `/api/context-pack-schema.json`
- `/api/decision-kit-schema.json`

### Agent-Facing Build Packs
**URL:** `/api/context-pack-index.json`

Use the index to select the smallest useful context pack by `languageIds`, `stackIds`, `projectTypes`, `requirements`, and `tags`. Prefer compact packs over full raw records when you want implementation memory without token bloat.

### Local Benchmark Skeleton

The first token-cost pilot lives in the repo under `/benchmarks/`. It compares `no-cache`, `raw-record`, and `compact-pack` bundles using local fixtures only, so it can be verified without a hosted backend.

---

## Usage Examples for Agents

### Example 1: Check whether a language recommendation is actually justified
- fetch `languages.json`
- compare candidate entries
- answer with tradeoffs, not just popularity

### Example 2: Compare Python and JavaScript for async work
- fetch both entries
- compare `patterns`, `tips`, and relevant use-case fit

### Example 3: Decide whether another language is worth introducing
- identify the bottleneck or constraint
- compare the current language against the proposed one
- state whether the gain is local, system-wide, or not worth the extra complexity

---

## Integration Guidelines

1. **Fetch once, cache locally.**
2. **Use stable `id` slugs.**
3. **Don’t scrape HTML when the JSON already contains the structured data.**
4. **Use CacheSphere as a second-opinion layer** for technical decisions, not as a black-box answer generator.
5. **Refetch periodically** because the catalogue evolves.

---

## Human-Readable Docs
- Home: `/index.html`
- Advisor: `/advisor.html`
- Compare: `/compare.html`
- Globe: `/globe.html`
- Use cases: `/use-cases.html`
- For AI tools: `/for-agents.html`
- FAQ: `/docs/faq.html`
- Quickstart: `/docs/quickstart.html`