Metadata-Version: 2.4
Name: cortyxia
Version: 0.1.13a1
Summary: The Memory Layer for Enterprise AI — persistent memory and 40% token cost reduction for any LLM stack
License: MIT
Project-URL: Homepage, https://www.cortyxia.com
Project-URL: Documentation, https://docs.cortyxia.com
Project-URL: Repository, https://github.com/simar5244/CortyxiaAPI.git
Project-URL: Issues, https://github.com/simar5244/CortyxiaAPI/issues
Keywords: cortyxia,llm,memory,ai,enterprise,context,rag,agent,chatbot,proxy,memory-layer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0

# Cortyxia Python SDK

[![PyPI](https://img.shields.io/pypi/v/cortyxia)](https://pypi.org/project/cortyxia/)
[![Python](https://img.shields.io/pypi/pyversions/cortyxia)](https://pypi.org/project/cortyxia/)
[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/simar5244/CortyxiaAPI/blob/main/LICENSE)

> **Your LLM app with a memory upgrade.**
> Drop-in persistent memory. 40% fewer tokens. One line to get started.

---

## Why Cortyxia?

Building LLM apps that "remember" across sessions shouldn't require a PhD in vector databases, embedding pipelines, or context-window math.

Cortyxia is a **drop-in memory layer** — you swap your `openai.chat.completions.create()` for `client.chat.completions.create()`, and suddenly your app remembers everything. No schema design. No Pinecone setup. No chunking strategies. It just works.

Under the hood: a 3-tier memory graph (raw → indexed → entity-linked) with ONNX extractors, cross-encoder reranking, and semantic relevance scoring. Sits as a transparent proxy — sub-50ms routing overhead, zero prompt changes, and fully compatible with whatever RAG or vector DB you're already running.

### What you get

- **Persistent memory** — conversations, facts, and context survive restarts
- **40% token cost reduction** — intelligent context assembly sends only what matters
- **Multi-provider routing** — Groq, OpenAI, Anthropic, Gemini, DeepSeek, xAI via one ISO token
- **Project isolation** — separate memory namespaces per team/project
- **Dev mode keys** — isolated context windows for agentic coding workflows

### What you DON'T need

- No vector DB setup (Pinecone, Weaviate, Chroma, etc.)
- No embedding pipeline
- No chunking / token-counting logic
- No config files to manage
- No signup forms — just an email

---

## The 30-Second Test

```bash
pip install cortyxia
```

Set your provider key, provider, and model in a `.env` file, then:

```python
from cortyxia import Cortyxia

client = Cortyxia()
key = client.initialize()   # Creates project + key from your .env

# Chat with memory
resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "My name is Alice"}]
)

# Later, in a new session:
resp2 = client.chat.completions.create(
    messages=[{"role": "user", "content": "What's my name?"}]
)
# It remembers. It answers "Alice".
```

No database connection strings. No index creation. One package. One line. Done.

---

## Installation

```bash
pip install cortyxia
```

- Python **>= 3.9**
- One dependency: `requests`
- Zero system packages (no ONNX, no CUDA drivers, no Rust toolchain)

That's it. If `requests` works, Cortyxia works.

---

## One-Shot Setup (Recommended)

Create a `.env` file in your project root:

```bash
# .env
CORTYXIA_EMAIL=you@example.com
API_KEY=gsk_your_groq_key_here
API_PROVIDER=groq
API_MODEL=llama-3.1-8b-instant
# Optional: DEV_MODE=true
```

Then one line:

```python
from cortyxia import Cortyxia

client = Cortyxia()
key = client.initialize()        # Creates "Default Project" + "Default Key"
print(key["iso_token"])          # Grab your ISO token
```

`.env` is parsed automatically — no `python-dotenv` dependency, no manual `load_dotenv()` call. We read it with `pathlib` (stdlib only).

---

## Migrating from OpenAI / LangChain / Raw HTTP

Already using `openai`? Swap is two lines:

```python
# Before
import openai
client = openai.OpenAI(api_key="sk-...")
resp = client.chat.completions.create(model="gpt-4o", messages=[...])

# After
from cortyxia import Cortyxia
client = Cortyxia()
resp = client.chat.completions.create(messages=[...])  # model auto-resolved
```

**Your prompts don't change.** Your message format doesn't change. The response shape is identical. If you don't like it, remove the import and go back. No lock-in.

---

## Chat

### Non-streaming

```python
from cortyxia import Cortyxia, answer

client = Cortyxia()

resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "What was I working on yesterday?"}]
)
print(answer(resp))   # Just the assistant text
```

### Streaming

```python
for line in client.chat.completions.stream(
    messages=[{"role": "user", "content": "Explain quantum computing"}]
):
    print(line, end="")
```

### Use a specific key (iso_token)

```python
resp = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    iso_token="iso-your-token-here"   # Overrides default key
)
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `messages` | `List[dict]` | Yes | OpenAI-format messages |
| `model` | `str` | No | Model ID (auto-resolved from key if omitted) |
| `iso_token` | `str` | No | Specific key to use |
| `temperature` | `float` | No | Sampling temperature |
| `max_tokens` | `int` | No | Max output tokens |

---

## Memory

### Add a memory node

```python
node = client.memory.add(
    content="User prefers Rust over Go for systems programming",
    tags=["preference", "language"]
)
```

### Query memory

```python
results = client.memory.query("What language does the user prefer?", limit=5)
for hit in results["hits"]:
    print(hit["content"])
```

### Query scoped to a specific key

```python
results = client.memory.query("deployment issues", iso_token="iso-your-token")
```

---

## Projects

```python
# List all projects
projects = client.projects.list()

# Create
project = client.projects.create("Agentic Coding", shared_memory_enabled=True)

# Get / Delete
project = client.projects.get(project["id"])
client.projects.delete(project["id"])
```

---

## Keys

### Create a key

```python
key = client.keys.create(
    project_id=client.project_id,
    label="Production Key",
    provider="groq",
    model="llama-3.1-8b-instant",
    provider_key="gsk_your_key_here",   # Auto-maps to correct provider field
)
```

### Create with explicit provider fields

```python
key = client.keys.create(
    project_id=client.project_id,
    label="OpenAI Key",
    provider="openai",
    model="gpt-4o",
    openai_key="sk-...",
)
```

### Dev mode key (isolated context)

```python
key = client.keys.create(
    project_id=client.project_id,
    label="Claude Agent",
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    dev_mode=True,
    dev_namespace="agent_1",
    recent_window_min=2,
    recent_window_max=8,
)
```

### Update

```python
# By key ID
client.keys.update(
    project_id=client.project_id,
    key_id=key["id"],
    model="llama-3.3-70b-versatile",
)

# By ISO token (no project_id needed)
client.keys.update_by_token(
    iso_token="iso-your-token",
    model="llama-3.3-70b-versatile",
)
```

### Delete

```python
# By key ID
client.keys.delete(client.project_id, key["id"])

# By ISO token
client.keys.delete_by_token("iso-your-token")
```

### List all keys

```python
for project in client.projects.list():
    for key in client.keys.list(project["id"]):
        print(key["iso_token"])
```

---

## Helper Functions

### `answer(response)` — Extract assistant text

```python
from cortyxia import answer

resp = client.chat.completions.create(messages=[...])
print(answer(resp))   # Clean string, no JSON digging
```

---

## Credential Storage

Cortyxia stores credentials in **two locations** for resilience:

| Location | Path | Priority |
|----------|------|----------|
| Project-local | `./.cortyxia/credentials.json` | 1st |
| Machine-global | `~/.cortyxia/credentials.json` | 2nd |

Both files are created with `0600` permissions. A `./.cortyxia/.gitignore` with `*` is auto-generated.

### Resolution Order

1. `CORTYXIA_EMAIL` env var triggers provisioning / override
2. `./.cortyxia/credentials.json` (per-project)
3. `~/.cortyxia/credentials.json` (machine-wide)
4. Auto-provision if credentials don't exist

**Email switching:** Change `CORTYXIA_EMAIL` to switch accounts. Each email has its own isolated project world.

```python
import os
os.environ["CORTYXIA_EMAIL"] = "work@company.com"
client = Cortyxia()
```

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CORTYXIA_EMAIL` | Yes (first run) | Email for provisioning |
| `API_KEY` | No | LLM provider API key (for `initialize()`) |
| `API_PROVIDER` | No | Provider name: `groq`, `openai`, `anthropic`, `gemini`, `deepseek`, `xai` |
| `API_MODEL` | No | Model ID (for `initialize()`) |
| `DEV_MODE` | No | `true` or `false` (default: `false`) |

---

## Error Handling

```python
from cortyxia import Cortyxia, CortyxiaError

try:
    client = Cortyxia()
    key = client.initialize()
except CortyxiaError as e:
    print(f"Setup failed: {e}")
```

---

## FAQ

**"What if Cortyxia goes down? Do my prompts break?"**

Your prompts don't change. The response shape is identical to OpenAI's. If Cortyxia is unavailable, swap back to your original provider in one line. Your code stays the same.

**"Do I need to redesign my app architecture?"**

No. If you're already calling `chat.completions.create()`, you change the import. That's it. Memory happens automatically in the background.

**"What about my existing vector DB / RAG pipeline?"**

You can keep it. Cortyxia handles the "I talked to this user 3 days ago" memory layer. Your RAG pipeline handles the "here are the docs" layer. They complement each other.

**"How much does this cost?"**

Cortyxia itself is free (MIT license). You only pay for your LLM provider usage (Groq, OpenAI, etc.). And because Cortyxia assembles smarter context, you typically use **fewer tokens** — so your bill goes down, not up.

**"Is my data safe?"**

- Credentials stored locally with `0600` permissions
- Each email has fully isolated project data
- No third-party analytics or telemetry
- Open source — you can audit every line

**"Can I use this in production?"**

Yes. The alpha tag means the API surface may evolve, but the core routing and memory layers are battle-tested. Pin your version: `pip install cortyxia==0.1.12a1`.

---

## Push to PyPI (Pre-release)

Bump the version in `pyproject.toml` (e.g., `0.1.12a1`):

```toml
[project]
name = "cortyxia"
version = "0.1.12a1"
```

Build and upload:

```bash
cd sdks/python
python -m build
python -m twine upload --repository pypi dist/*
```

Or use TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
```

Install the pre-release:

```bash
pip install --pre cortyxia
```

---

## License

MIT
