Metadata-Version: 2.4
Name: mftsccs
Version: 0.1.14
Summary: A Python library for Concept-Connection System (CCS) - offline-first knowledge graph management
Author-email: Boomconsole <nischal@boomconsole.com>
License: MIT
Project-URL: Homepage, https://freeschema.com
Project-URL: Documentation, https://freeschema.com
Project-URL: Repository, https://github.com/Mentor-Friends/CCS-PYTHON
Project-URL: Issues, https://github.com/Mentor-Friends/CCS-PYTHON/issues
Keywords: ccs,library,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# CCS

A Python library for CCS functionality.

## Installation

### From source (development mode)

```bash
# Clone the repository
git clone https://github.com/yourusername/ccs.git
cd ccs

# Install in development mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"
```

### From PyPI (once published)

```bash
pip install ccs
```

## Usage

### Initialization

```python
from ccs import init, CCSConfig

await init(
    url="https://api.example.com",
    nodeUrl="https://node.example.com",
    applicationName="MyApp",
    config=CCSConfig(storagePath="./data/ccs/")
)
```

### Get instance concept by character value and type

Fetches a concept from the backend that matches a given character value and type string (e.g. a URL tagged as `"the_source_url"`).

```python
from ccs.api import GetInstanceConceptByCharacterType

concept = await GetInstanceConceptByCharacterType(
    characterValue="https://www.google.com/maps/place/gorjana/data=...",
    type="the_source_url",
)

if concept.id != 0:
    print(concept.id)             # server-assigned concept ID
    print(concept.characterValue) # the matched character value
```

**Request body sent to `/api/get_instance_concept_by_character_type`:**

```json
{
    "characterValue": "https://...",
    "type": "the_source_url"
}
```

Returns a `Concept` object. If no match is found or an error occurs, returns a default empty `Concept` with `id=0`.

### Login output formatting (frontend-friendly)

Use the package to call backend login and return a normalized payload that your frontend can store directly.

```python
from ccs import init, CCSConfig, login, format_login_payload

await init(
    url="https://boomconsole.com",
    nodeUrl="https://boomconsole.com",
    applicationName="boomconsole",
    config=CCSConfig(storagePath="./data/ccs/")
)

# Calls /api/auth/login and returns normalized payload.
# By default this does NOT persist login data.
payload = await login("user@example.com", "password")
print(payload)

# If you already have raw backend login JSON, just format it:
normalized = format_login_payload(raw_login_response, fallback_email="user@example.com")
```

Normalized output shape:

```json
{
  "token": "...",
  "refreshToken": "...",
  "email": "user@example.com",
  "userId": 10489,
  "userConcept": 100417172,
  "entityId": 100827857,
  "amcode": "base64-encoded-roles-json"
}
```

Optional storage behavior:

```python
# Only if you explicitly want package-level storage:
payload = await login("user@example.com", "password", store_session=True, persist=True)
```

## Project Structure

```
CCS-Python/
├── pyproject.toml          # Package configuration
├── README.md               # This file
├── src/
│   └── ccs/                # Main package
│       ├── __init__.py     # Package initialization & exports
│       ├── core.py         # Core functionality
│       └── utils.py        # Utility functions
├── tests/                  # Test suite
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/                   # Documentation (optional)
```

## Development

### Running tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=ccs
```

### Code formatting

```bash
# Format code with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/
```

### Type checking

```bash
mypy src/
```

## Building & Publishing

### Build the package

```bash
pip install build
python -m build
```

This creates distribution files in the `dist/` directory:
- `ccs-0.1.0.tar.gz` (source distribution)
- `ccs-0.1.0-py3-none-any.whl` (wheel distribution)

### Publish to PyPI

```bash
pip install twine

# Upload to TestPyPI first (recommended)
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*
```

## License

MIT License - see LICENSE file for details.
