cobjectric 1.1.0

Complex Object Metric - A library for measuring complexity of Python objects

Cobjectric

Complex Object Metric - A Python library for computing metrics on complex objects (JSON, dictionaries, lists, etc.).

📖 Description

Cobjectric is a library designed to help developers calculate metrics on complex objects such as JSON, dictionaries, and arrays. It was originally created for Machine Learning projects where comparing and evaluating generated JSON structures against ground truth data was a repetitive manual task.

🚀 Getting Started

For Users

pip install cobjectric

For Development

Prerequisites

• Python 3.13.9 or higher
• uv - Fast Python package installer

1. Install dependencies with uv:

uv sync --dev

2. Install pre-commit hooks:

uv run pre-commit install --hook-type pre-push

🛠️ Development

Available Commands

The project uses invoke for task management.

To see all available commands:

uv run inv --list
# or shorter:
uv run inv -l

To get help on a specific command:

uv run inv --help <command>
# Example:
uv run inv --help precommit

📚 Usage

Quick Example

Cobjectric allows you to define typed models and compute fill rate metrics to measure data completeness:

from cobjectric import BaseModel, Spec

class Person(BaseModel):
    name: str = Spec(fill_rate_func=lambda x: len(x) / 100)
    age: int
    email: str

# Create from dictionary
person = Person.from_dict({
    "name": "John Doe",
    "age": 30,
    "email": "[e-mail]",
})

# Compute fill rate (scoring)
result = person.compute_fill_rate()

print(result.fields.name.value)   # 0.08 (len("John Doe") = 8, 8/100)
print(result.fields.age.value)    # 1.0 (present)
print(result.fields.email.value)  # 1.0 (present)
print(result.mean())              # 0.693... (average fill rate)

Fill rate measures how "complete" each field is (0.0 = missing, 1.0 = present). You can define custom fill rate functions or use the default (0.0 for missing, 1.0 for present).

See the documentation for more details on nested models, list fields, normalizers, and advanced features.

Features

• Fill Rate Scoring: Compute completeness metrics (fill rate) for all fields with statistical aggregation
• Typed Models: Define models with type annotations and automatic validation
• Nested Models: Support for nested model structures with recursive fill rate computation
• Field Normalizers: Transform field values before validation
• Flexible Types: Support for optional fields, union types, typed dicts, and lists

For complete feature list and details, see the documentation.

Documentation

For more information, see the documentation:

• Quick Start - Get started in 5 minutes
• BaseModel and Fields - Detailed guide and API reference

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Citing Cobjectric

If you use Cobjectric in your research or projects, please consider citing it:

@software{cobjectric2025,
  author = {Nigiva},
  title = {Cobjectric: A Library for Computing Metrics on Complex Objects},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/nigiva/cobjectric}},
  version = {1.1.0}
}