# SymPy Migration Guide

This guide is for Python users moving SymPy scripts to Kalika. The shortest path
is the `kalika_sdk` Python package, which exposes SymPy-like helpers while
delegating computation to the local TypeScript SDK.

Official source references used while preparing this guide:

- SymPy intro:
  <https://docs.sympy.org/latest/tutorials/intro-tutorial/intro.html>
- SymPy matrices:
  <https://docs.sympy.org/latest/tutorials/intro-tutorial/matrices.html>

## Quick Mapping

| SymPy                      | Kalika Python                                   | Kalika TypeScript                          | Notes                                                                                 |
| -------------------------- | ----------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `symbols("x y")`           | `symbols("x y")`                                | String variables in SDK requests           | Multiple symbols unpack like SymPy.                                                   |
| `simplify(expr)`           | `simplify(expr)`                                | `sdk.simplify(expr)`                       | Python helper returns an expression facade; TypeScript returns `ComputeResponse`.     |
| `diff(expr, x)`            | `diff(expr, x)`                                 | `sdk.differentiate(expr, "x")`             | Keep variable identity explicit when moving to TypeScript.                            |
| `integrate(expr, x)`       | `integrate(expr, x)`                            | `sdk.integrate(expr, "x")`                 | Definite integration should be handled with numerical/domain packages when needed.    |
| `solve(eqn, x)`            | `solve(eqn, x)`                                 | `sdk.solve(eqn, "x")`                      | Current SDK solve facade is intentionally narrow and metadata-rich.                   |
| `series(expr, x, a, n)`    | `series(expr, x, a, n)`                         | `sdk.series(expr, "x", a, n)`              | Kalika also has `taylorAsymptoticExpansion` for analysis workflows.                   |
| `limit(expr, x, a)`        | `limit(expr, x, a)`                             | `sdk.limit(expr, "x", a)`                  | Result metadata records engine and verification status.                               |
| `N(expr)` / `expr.evalf()` | `N(expr, substitutions)` or `client.evalf(...)` | `sdk.evaluate(...)`                        | Numeric substitution maps are explicit.                                               |
| `Matrix([...])`            | `Matrix.from_rows([...])`                       | `sdk.matrix(...)` or `rationalMatrix(...)` | Use SDK matrices for numeric local compute and `@kalika/algebra` for exact rationals. |
| `latex(expr)`              | Use TypeScript `serializeExprToLatex`           | `serializeExprToLatex`                     | Expression serialization lives in `@kalika/core`.                                     |

## API Comparison

SymPy usually exposes one Python namespace. Kalika splits the API into:

- `kalika_sdk`: Python facade for local SDK computations.
- `@kalika/sdk`: TypeScript facade for browser, Node.js, and service code.
- `@kalika/core`: expression ASTs, serialization, rewrite rules, derivations,
  and equality saturation.
- Domain packages such as `@kalika/algebra`, `@kalika/analysis`,
  `@kalika/number-theory`, and `@kalika/quantum-field-theory`.

SymPy expression objects are rich Python objects. Kalika Python expressions are
lightweight facades designed for familiar operator syntax and bridge calls. When
you need exact AST-level transformations, move that part of the port to
`@kalika/core`.

## Python Porting Pattern

```python
from kalika_sdk import Matrix, N, KalikaClient, diff, integrate, symbols

x, y = symbols("x y")
client = KalikaClient()

derivative = diff(x**3 + 2 * x, x)
integral = integrate("sin(x)", x)
numeric = N("x^2 + y", {"x": 4, "y": 2})
determinant = client.matrix("determinant", matrix=Matrix.from_rows([[1, 2], [3, 5]]))

print(derivative, integral, numeric, determinant.value)
print(client.derivation_for(client.diff("x^2", "x")))
```

## TypeScript Service Pattern

```ts
import { createKalikaSdk } from '@kalika/sdk';

const sdk = await createKalikaSdk();

const jobs = await sdk.batch([
  {
    kind: 'symbolic',
    operation: 'differentiate',
    payload: { expression: 'x^3', variable: 'x' },
  },
  {
    kind: 'evaluate',
    payload: { expression: 'x^2 + y', variables: { x: 4, y: 2 } },
  },
]);

console.log(jobs.result.jobs);
```

## Migration Checklist

- Keep Python notebooks on `kalika_sdk` when you only need SymPy-like calls.
- Move service, browser, and batch workloads to `@kalika/sdk`.
- Replace direct introspection of SymPy internals with `@kalika/core` AST and
  serialization functions.
- Route exact matrices, rings, groups, and modules to `@kalika/algebra`.
- Route advanced transforms, Hilbert spaces, and asymptotics to
  `@kalika/analysis`.
- Preserve result metadata; do not discard derivation and verification fields
  when wrapping Kalika calls in legacy APIs.
