Metadata-Version: 2.4
Name: tagmap
Version: 0.1.18
Summary: Fast data structure for managing tags and metadata with efficient queries
Author: originalsouth
License: UNICODE
Project-URL: Homepage, https://github.com/originalsouth/tagmap.py
Project-URL: Repository, https://github.com/originalsouth/tagmap.py
Keywords: tags,metadata,data-structure,c++
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.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
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# TagMap

A data structure for managing tags and metadata with support for efficient intersection and union queries. Implemented in C++ with Python bindings via pybind11.

## Overview

TagMap provides a dictionary-like container where each key maps to a set of tags. It supports querying for keys that match specific tag combinations using AND (intersection) and OR (union) operations.

## Characteristics

- O(1) average case for single tag operations (add, remove, check)
- O(k·m) for AND queries (k = result size, m = avg tags per key)
- O(n) for OR queries (n = total keys matching any tag)
- Inverted index structure for fast queries
- C++ implementation with Python 3.8+ compatibility

## Install

Install from PyPI:

```bash
pip install tagmap
```

Requires Python 3.8 or later. Pre-built wheels available for Linux, macOS, and Windows. For platform-specific instructions, see [INSTALLATION.md](docs/INSTALLATION.md).

## Usage

```python
import tagmap

m = tagmap.TagMap()

# Set tags for keys
m["alice"] = {"dev", "python"}
m["bob"] = {"dev", "cpp"}
m["carol"] = ["design", "python"]

# Query: keys with both "dev" AND "python"
m.query("dev", "python")        # ['alice']

# Query: keys with "python" OR "ops"
m.query_any("python", "ops")    # ['alice', 'carol']

# Check if key has tag
m.has_tag("alice", "python")    # True

# Add or remove tags
m.add_tag("alice", "ml")
m.remove_tag("bob", "dev")
```

## Documentation

- [API Reference](docs/API.md) - Complete method documentation
- [Examples](docs/EXAMPLES.md) - Usage patterns
- [Architecture](docs/ARCHITECTURE.md) - Implementation details and complexity analysis
- [Installation](docs/INSTALLATION.md) - Setup instructions for all platforms

## Examples

### Team Skills

```python
team = tagmap.TagMap({
    "alice": ["python", "typescript", "backend"],
    "bob": ["cpp", "rust", "backend"],
    "carol": ["ux", "ui", "design"],
})

team.query("python")             # ['alice']
team.query("backend")            # ['alice', 'bob']
team.query("python", "backend")  # ['alice']
```

See [EXAMPLES.md](docs/EXAMPLES.md) for additional usage patterns.

## Performance

Tag operations (add, remove, check): O(1) average case
AND queries (all tags): O(k·m) where k = result size, m = avg tags per key
OR queries (any tag): O(n) where n = sum of keys matching each tag

See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed complexity analysis and benchmarks.

## Building from Source

Clone and build:

```bash
git clone https://github.com/originalsouth/tagmap.py.git
cd tagmap.py

python -m venv venv
source venv/bin/activate

pip install pybind11 pytest
pip install -e .
```

Run tests:

```bash
pytest test_tagmap.py -v
```

Requirements: Python 3.8+, C++20 compiler, pybind11. Build uses `-Ofast -march=native` optimizations.

For detailed build instructions, see [INSTALLATION.md](docs/INSTALLATION.md).

## License

MIT License. See [LICENSE](LICENSE) for details.

## Repository

- GitHub: https://github.com/originalsouth/tagmap.py
- Issues: https://github.com/originalsouth/tagmap.py/issues
- Releases: https://github.com/originalsouth/tagmap.py/releases
