Metadata-Version: 2.4
Name: cardbox
Version: 0.0.1
Summary: Card-box based context management core library.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Intelligent-Internet/CG-Cardbox
Project-URL: Repository, https://github.com/Intelligent-Internet/CG-Cardbox
Project-URL: Issues, https://github.com/Intelligent-Internet/CG-Cardbox/issues
Keywords: cardbox,cards,context,llm,postgres
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.42.6
Requires-Dist: httpx
Requires-Dist: instructor
Requires-Dist: litellm
Requires-Dist: pydantic<3,>=2
Requires-Dist: pydantic-settings>=2.0.3
Requires-Dist: psycopg[binary]
Requires-Dist: psycopg-pool
Requires-Dist: requests
Requires-Dist: tenacity==9.1.2
Requires-Dist: typing_extensions
Requires-Dist: uuid6
Provides-Extra: test
Requires-Dist: respx==0.22.0; extra == "test"
Provides-Extra: interactions
Requires-Dist: google-genai; extra == "interactions"
Dynamic: license-file

<p align="left">
    &nbspEnglish&nbsp | <a href="README_CN.md">中文</a>&nbsp 
</p>

# cardbox

`cardbox` is a data and context orchestration library centered around `Card` and `CardBox`.

## Core Design Principles

### 1. Immutable Core Data

- `Card` is the atomic unit of information.
- Logical "updates" are done by creating a new `Card` (for example, `Card.update(...)` returns a new object with a new `card_id`).
- This makes transformation flows traceable and auditable.

### 2. Linear Context Container

- `CardBox` is an ordered collection of `card_id`s.
- The main workflow processes context in linear order to keep complexity low.
- Multi-turn context and strategy transformations are all built around `CardBox`.

### 3. Centralized State Management

- `CardStore` is the read/write entry point for cards and delegates persistence to storage adapters.
- `CardBox` stores references only; actual card data is loaded from the storage layer.

### 4. Strategy-Based Extensibility

- Business logic is encapsulated in independent `Strategy` units.
- `ContextEngine.transform(...)` orchestrates strategy chains with low coupling between strategies.
- Built-in examples: `ExtractCodeStrategy`, `PdfToTextStrategy`, `InlineTextFileContentStrategy`.

### 5. Explicit Traceability

- `ContextEngine` can log `Card` and `CardBox` transformation history based on `history_level`.
- `trace_id` spans an entire processing flow for correlated auditing.

## Core Components

- `Card`: Supports text, JSON, tool calls, file references, and more.
- `CardBox`: Ordered sequence of context references.
- `ContextEngine`: Provides `transform`, `to_api`, and `call_model`.
- `AsyncPostgresStorageAdapter`: Async PostgreSQL persistence.
- `LLMAdapter`: Unified LLM access (LiteLLM / optional Interactions backend).

## Installation

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

From PyPI:

```bash
pip install cardbox
```

Optional extras:

```bash
pip install -e .[test]
pip install -e .[interactions]
```

If you want the packaged demo command through `uv`:

```bash
uv tool install cardbox
cardbox
```

## PostgreSQL Configuration

Set one of the following DSN environment variables:

```bash
export POSTGRES_STORAGE_ADAPTER_DSN="postgresql://user:pass@localhost:5432/cardbox_db"
# or
export CARD_BOX_POSTGRES_DSN="postgresql://user:pass@localhost:5432/cardbox_db"
```

## Run the Demo

`main.py` demonstrates a minimal end-to-end flow:

1. Initialize `AsyncPostgresStorageAdapter` (with optional auto bootstrap).
2. Create and persist `Card` instances.
3. Save and load a `CardBox`.
4. Print the loaded result.

Run:

```bash
python main.py
```

or, after installation:

```bash
cardbox
```

## Run Tests

```bash
python -m unittest discover -s tests -p 'test_*.py' -v
```

Notes:

- `tests/test_llm_providers.py` depends on external model environment variables and will be skipped when not configured.
- Other tests prefer local stubs and avoid real external services.

## Override Configuration

Use `configure` at startup to override default settings:

```python
from cardbox.config import configure

configure({
    "POSTGRES_STORAGE_ADAPTER": {
        "dsn": "postgresql://user:pass@localhost:5432/cardbox_db",
        "auto_bootstrap": True,
    },
    "LLM_BACKEND": "litellm",
})
```
