# ShadowAI
🚀 An AI-powered intelligent mock data generation library
[](https://badge.fury.io/py/shadowai)
[](https://github.com/KevinZhang19870314/shadowai/actions/workflows/ci.yml)
[](https://github.com/KevinZhang19870314/shadowai/actions/workflows/release.yml)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
ShadowAI is a powerful Python library that uses AI technology to generate high-quality simulated data. Through a flexible rule engine, you can easily generate structured JSON data.
## 🎯 Design Philosophy
ShadowAI provides flexible and easy-to-use API design, supporting various usage scenarios from simple to complex, allowing users to get started quickly while maintaining powerful customization capabilities.
## 🆚 Comparison with Traditional Mock Libraries
### Core Differences
| Feature | ShadowAI | Traditional Mock Libraries (like faker.js) |
|---------|--------|---------------------------------------------|
| **Generation Method** | AI-powered intelligent generation | Predefined algorithms |
| **Configuration Complexity** | Minimal (description-based) | Medium (requires API combination) |
| **Data Quality** | High (semantic understanding) | Medium (template-based) |
| **Business Relevance** | Strong (context-aware) | Weak (generic patterns) |
| **Generation Speed** | Slow (AI calls) | Very fast (local computation) |
| **Extensibility** | High (AI adaptation) | Medium (requires development) |
### ShadowAI's Unique Advantages
#### 🧠 Intelligent Understanding
```python
# ShadowAI - One line of code, intelligent understanding of business meaning
shadow_ai.generate("company_email") # Automatically generates company-formatted emails
# Traditional library - Requires manual combination of multiple APIs
faker.internet.email(
faker.person.firstName(),
faker.person.lastName(),
faker.internet.domainName()
)
```
#### 🎯 Business Scenario Driven
```python
# ShadowAI - Business rule packages ensure data logical consistency
developer_profile = RulePackage(
name="senior_developer",
rules=["name", "email", "programming_language", "years_experience", "github_username"]
)
# Generated data automatically maintains logical relationships: high experience corresponds to advanced programming languages
```
#### 🔧 Minimal Configuration
```python
# ShadowAI - Descriptive configuration
Rule(
name="medical_record_id",
description="Generate HIPAA-compliant patient ID",
constraints={"format": "anonymized"}
)
# Traditional library - Requires custom development
def generate_medical_id():
# Lots of custom logic...
```
### Use Case Selection
#### ✅ Recommended ShadowAI Scenarios
- **Complex business testing**: Requires logical relationships between data
- **Prototype demonstrations**: Needs highly realistic sample data
- **Industry-specific data**: Medical, financial, and other professional domains
- **API documentation examples**: Automatically generates business-compliant response examples
- **Rapid iteration**: Frequently adjusting data generation rules
#### ✅ Recommended Traditional Library Scenarios
- **High performance requirements**: Bulk generation of large amounts of data
- **CI/CD pipelines**: Automated testing environments
- **Simple standard data**: Basic names, emails, phone numbers
- **Offline environments**: No network connection restrictions
- **Cost-sensitive**: Avoiding AI API call costs
### 💡 Best Practice Recommendations
**Hybrid Usage Strategy** - Leverage the advantages of both:
```python
# 1. Use ShadowAI to design data templates
business_template = shadow_ai.generate(complex_business_package)
# 2. Use traditional libraries for bulk data population
for i in range(1000):
test_data = apply_template_with_faker(business_template)
```
**Selection Guide**:
- 🎯 Pursue **data quality** and **business relevance** → Choose **ShadowAI**
- ⚡ Pursue **generation speed** and **simplicity** → Choose **Traditional Mock Libraries**
- 🔄 Combine both → Get **best development experience**
## ✨ Features
- 🤖 **AI-driven**: Based on Agno framework, supports multiple LLM models
- 📝 **Flexible rules**: Supports rule records, rule combinations, and rule packages
- 📊 **Table generation**: Generate tabular data in Markdown, CSV, HTML, and JSON formats
- 📄 **Multi-format support**: Supports JSON and YAML format rule definitions
- 🎯 **Precise output**: Generates structured JSON data and formatted tables
- 📦 **Ready to use**: Built-in common rule packages and table templates
- ⚡ **Minimal configuration**: Descriptive configuration, quick start
## 📦 Installation
```bash
pip install shadowai
```
## 🚀 Quick Start
### Basic Usage
```python
from shadow_ai import ShadowAI
# Create ShadowAI instance
shadow_ai = ShadowAI()
# Use string directly
result = shadow_ai.generate("email")
print(result) # {"email": "john.doe@example.com"}
# Generate multiple fields
result = shadow_ai.generate(["email", "name", "age"])
print(result) # {"email": "...", "name": "...", "age": ...}
# Quick method
result = shadow_ai.quick("email", "name", "phone")
print(result) # {"email": "...", "name": "...", "phone": "..."}
```
### Creating Custom Rules
```python
from shadow_ai import Rule, RuleCombination, RulePackage
# Create single rule
email_rule = Rule(name="email")
company_rule = Rule(name="company_name")
# Generate data
result = shadow_ai.generate(email_rule)
print(result) # {"email": "user@example.com"}
# Create rule combination
user_combo = RuleCombination(
name="user_profile",
rules=["name", "email", "phone"]
)
# Create rule package
user_package = RulePackage(
name="user",
rules=["username", "email", "age", "location"]
)
result = shadow_ai.generate(user_package)
print(result) # Complete user information
```
### Using Pre-built Rules
```python
from shadow_ai.rules import email_rule, name_rule
from shadow_ai.rules.packages import person_package
# Use predefined rules
result = shadow_ai.generate(email_rule)
print(result) # {"email": "john.doe@example.com"}
# Use predefined packages
result = shadow_ai.generate(person_package)
print(result)
# {
# "fullname": "John Smith",
# "age": 25,
# "email": "john.smith@email.com"
# }
```
### Advanced Custom Rules
```python
from shadow_ai import Rule
# Detailed rule configuration
custom_rule = Rule(
name="company",
description="Generate a technology company name",
examples=["TechCorp", "DataFlow", "CloudByte"],
constraints={"type": "string", "style": "modern"}
)
result = shadow_ai.generate(custom_rule)
```
### Table Generation
```python
from shadow_ai import ShadowAI, TableOutputFormat, TableRule, Rule
shadow_ai = ShadowAI()
# Quick table generation
table = shadow_ai.quick_table(
"products",
"id", "name", "price", "category",
rows=5,
output_format=TableOutputFormat.MARKDOWN
)
print(table)
# Generates a formatted Markdown table
# Use built-in templates
user_table = shadow_ai.generate_table_from_template(
"user_profiles",
rows=10,
output_format=TableOutputFormat.CSV,
save_to_file="users.csv"
)
# Custom table with rules
custom_table = TableRule.create(
name="survey",
columns=[
Rule(name="response_id").with_examples("RESP001", "RESP002"),
Rule(name="score").with_constraints(type="integer", min=1, max=10),
Rule(name="feedback").with_examples("Great!", "Good", "Average")
],
rows_count=8
)
result = shadow_ai.generate_table(custom_table, TableOutputFormat.MARKDOWN)
# List available templates
templates = shadow_ai.list_table_templates()
print(templates) # ['user_profiles', 'product_catalog', 'sales_data', 'employees', 'financial_data']
```
## 📖 Documentation
For detailed documentation, please check the [docs/](docs/) directory.
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
## 📄 License
MIT License - see [LICENSE](LICENSE) file.
Raw data
{
"_id": null,
"home_page": null,
"name": "shadowai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, mock, data, generation, testing, agno, table, csv, markdown",
"author": null,
"author_email": "Kevin Zhang <kevinzhang19870314@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4e/74/a14690b545798ac3723e61a91d60518300eab0f5fba4616fd6c33eb1a57e/shadowai-0.2.0.tar.gz",
"platform": null,
"description": "# ShadowAI\n\n\ud83d\ude80 An AI-powered intelligent mock data generation library\n\n[](https://badge.fury.io/py/shadowai)\n[](https://github.com/KevinZhang19870314/shadowai/actions/workflows/ci.yml)\n[](https://github.com/KevinZhang19870314/shadowai/actions/workflows/release.yml)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nShadowAI is a powerful Python library that uses AI technology to generate high-quality simulated data. Through a flexible rule engine, you can easily generate structured JSON data.\n\n## \ud83c\udfaf Design Philosophy\n\nShadowAI provides flexible and easy-to-use API design, supporting various usage scenarios from simple to complex, allowing users to get started quickly while maintaining powerful customization capabilities.\n\n## \ud83c\udd9a Comparison with Traditional Mock Libraries\n\n### Core Differences\n\n| Feature | ShadowAI | Traditional Mock Libraries (like faker.js) |\n|---------|--------|---------------------------------------------|\n| **Generation Method** | AI-powered intelligent generation | Predefined algorithms |\n| **Configuration Complexity** | Minimal (description-based) | Medium (requires API combination) |\n| **Data Quality** | High (semantic understanding) | Medium (template-based) |\n| **Business Relevance** | Strong (context-aware) | Weak (generic patterns) |\n| **Generation Speed** | Slow (AI calls) | Very fast (local computation) |\n| **Extensibility** | High (AI adaptation) | Medium (requires development) |\n\n### ShadowAI's Unique Advantages\n\n#### \ud83e\udde0 Intelligent Understanding\n```python\n# ShadowAI - One line of code, intelligent understanding of business meaning\nshadow_ai.generate(\"company_email\") # Automatically generates company-formatted emails\n\n# Traditional library - Requires manual combination of multiple APIs\nfaker.internet.email(\n faker.person.firstName(),\n faker.person.lastName(), \n faker.internet.domainName()\n)\n```\n\n#### \ud83c\udfaf Business Scenario Driven\n```python\n# ShadowAI - Business rule packages ensure data logical consistency\ndeveloper_profile = RulePackage(\n name=\"senior_developer\",\n rules=[\"name\", \"email\", \"programming_language\", \"years_experience\", \"github_username\"]\n)\n# Generated data automatically maintains logical relationships: high experience corresponds to advanced programming languages\n```\n\n#### \ud83d\udd27 Minimal Configuration\n```python\n# ShadowAI - Descriptive configuration\nRule(\n name=\"medical_record_id\", \n description=\"Generate HIPAA-compliant patient ID\",\n constraints={\"format\": \"anonymized\"}\n)\n\n# Traditional library - Requires custom development\ndef generate_medical_id():\n # Lots of custom logic...\n```\n\n### Use Case Selection\n\n#### \u2705 Recommended ShadowAI Scenarios\n- **Complex business testing**: Requires logical relationships between data\n- **Prototype demonstrations**: Needs highly realistic sample data \n- **Industry-specific data**: Medical, financial, and other professional domains\n- **API documentation examples**: Automatically generates business-compliant response examples\n- **Rapid iteration**: Frequently adjusting data generation rules\n\n#### \u2705 Recommended Traditional Library Scenarios\n- **High performance requirements**: Bulk generation of large amounts of data\n- **CI/CD pipelines**: Automated testing environments\n- **Simple standard data**: Basic names, emails, phone numbers\n- **Offline environments**: No network connection restrictions\n- **Cost-sensitive**: Avoiding AI API call costs\n\n### \ud83d\udca1 Best Practice Recommendations\n\n**Hybrid Usage Strategy** - Leverage the advantages of both:\n```python\n# 1. Use ShadowAI to design data templates\nbusiness_template = shadow_ai.generate(complex_business_package)\n\n# 2. Use traditional libraries for bulk data population \nfor i in range(1000):\n test_data = apply_template_with_faker(business_template)\n```\n\n**Selection Guide**:\n- \ud83c\udfaf Pursue **data quality** and **business relevance** \u2192 Choose **ShadowAI**\n- \u26a1 Pursue **generation speed** and **simplicity** \u2192 Choose **Traditional Mock Libraries**\n- \ud83d\udd04 Combine both \u2192 Get **best development experience**\n\n## \u2728 Features\n\n- \ud83e\udd16 **AI-driven**: Based on Agno framework, supports multiple LLM models\n- \ud83d\udcdd **Flexible rules**: Supports rule records, rule combinations, and rule packages\n- \ud83d\udcca **Table generation**: Generate tabular data in Markdown, CSV, HTML, and JSON formats\n- \ud83d\udcc4 **Multi-format support**: Supports JSON and YAML format rule definitions\n- \ud83c\udfaf **Precise output**: Generates structured JSON data and formatted tables\n- \ud83d\udce6 **Ready to use**: Built-in common rule packages and table templates\n- \u26a1 **Minimal configuration**: Descriptive configuration, quick start\n\n## \ud83d\udce6 Installation\n\n```bash\npip install shadowai\n```\n\n## \ud83d\ude80 Quick Start\n\n### Basic Usage\n\n```python\nfrom shadow_ai import ShadowAI\n\n# Create ShadowAI instance\nshadow_ai = ShadowAI()\n\n# Use string directly\nresult = shadow_ai.generate(\"email\")\nprint(result) # {\"email\": \"john.doe@example.com\"}\n\n# Generate multiple fields\nresult = shadow_ai.generate([\"email\", \"name\", \"age\"])\nprint(result) # {\"email\": \"...\", \"name\": \"...\", \"age\": ...}\n\n# Quick method\nresult = shadow_ai.quick(\"email\", \"name\", \"phone\")\nprint(result) # {\"email\": \"...\", \"name\": \"...\", \"phone\": \"...\"}\n```\n\n### Creating Custom Rules\n\n```python\nfrom shadow_ai import Rule, RuleCombination, RulePackage\n\n# Create single rule\nemail_rule = Rule(name=\"email\")\ncompany_rule = Rule(name=\"company_name\")\n\n# Generate data\nresult = shadow_ai.generate(email_rule)\nprint(result) # {\"email\": \"user@example.com\"}\n\n# Create rule combination\nuser_combo = RuleCombination(\n name=\"user_profile\",\n rules=[\"name\", \"email\", \"phone\"]\n)\n\n# Create rule package\nuser_package = RulePackage(\n name=\"user\", \n rules=[\"username\", \"email\", \"age\", \"location\"]\n)\n\nresult = shadow_ai.generate(user_package)\nprint(result) # Complete user information\n```\n\n### Using Pre-built Rules\n\n```python\nfrom shadow_ai.rules import email_rule, name_rule\nfrom shadow_ai.rules.packages import person_package\n\n# Use predefined rules\nresult = shadow_ai.generate(email_rule)\nprint(result) # {\"email\": \"john.doe@example.com\"}\n\n# Use predefined packages\nresult = shadow_ai.generate(person_package)\nprint(result)\n# {\n# \"fullname\": \"John Smith\", \n# \"age\": 25,\n# \"email\": \"john.smith@email.com\"\n# }\n```\n\n### Advanced Custom Rules\n\n```python\nfrom shadow_ai import Rule\n\n# Detailed rule configuration\ncustom_rule = Rule(\n name=\"company\",\n description=\"Generate a technology company name\",\n examples=[\"TechCorp\", \"DataFlow\", \"CloudByte\"],\n constraints={\"type\": \"string\", \"style\": \"modern\"}\n)\n\nresult = shadow_ai.generate(custom_rule)\n```\n\n### Table Generation\n\n```python\nfrom shadow_ai import ShadowAI, TableOutputFormat, TableRule, Rule\n\nshadow_ai = ShadowAI()\n\n# Quick table generation\ntable = shadow_ai.quick_table(\n \"products\", \n \"id\", \"name\", \"price\", \"category\",\n rows=5,\n output_format=TableOutputFormat.MARKDOWN\n)\nprint(table)\n# Generates a formatted Markdown table\n\n# Use built-in templates\nuser_table = shadow_ai.generate_table_from_template(\n \"user_profiles\", \n rows=10,\n output_format=TableOutputFormat.CSV,\n save_to_file=\"users.csv\"\n)\n\n# Custom table with rules\ncustom_table = TableRule.create(\n name=\"survey\",\n columns=[\n Rule(name=\"response_id\").with_examples(\"RESP001\", \"RESP002\"),\n Rule(name=\"score\").with_constraints(type=\"integer\", min=1, max=10),\n Rule(name=\"feedback\").with_examples(\"Great!\", \"Good\", \"Average\")\n ],\n rows_count=8\n)\n\nresult = shadow_ai.generate_table(custom_table, TableOutputFormat.MARKDOWN)\n\n# List available templates\ntemplates = shadow_ai.list_table_templates()\nprint(templates) # ['user_profiles', 'product_catalog', 'sales_data', 'employees', 'financial_data']\n```\n\n## \ud83d\udcd6 Documentation\n\nFor detailed documentation, please check the [docs/](docs/) directory.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered mock data generation library with flexible rule engine and table generation support",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/KevinZhang19870314/shadowai/issues",
"Documentation": "https://github.com/KevinZhang19870314/shadowai#readme",
"Homepage": "https://github.com/KevinZhang19870314/shadowai",
"Repository": "https://github.com/KevinZhang19870314/shadowai"
},
"split_keywords": [
"ai",
" mock",
" data",
" generation",
" testing",
" agno",
" table",
" csv",
" markdown"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6fa8222be9be08e1e112d5b8e28e211f5e0af29e4f95de95552885bc6548064f",
"md5": "e370df1e30f4d7e4501bae2f7edf2826",
"sha256": "3d62911692da35ec0520a8d977d89461a836319fc35522de9ac36f227295b539"
},
"downloads": -1,
"filename": "shadowai-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e370df1e30f4d7e4501bae2f7edf2826",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30441,
"upload_time": "2025-08-07T08:33:01",
"upload_time_iso_8601": "2025-08-07T08:33:01.356790Z",
"url": "https://files.pythonhosted.org/packages/6f/a8/222be9be08e1e112d5b8e28e211f5e0af29e4f95de95552885bc6548064f/shadowai-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e74a14690b545798ac3723e61a91d60518300eab0f5fba4616fd6c33eb1a57e",
"md5": "96bc25d215fd343599ee1f5853d3d0ee",
"sha256": "cddff3984f7ceea762b342e4822477eff6efa32a5fb0d0b286f50ea4358ad0a2"
},
"downloads": -1,
"filename": "shadowai-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "96bc25d215fd343599ee1f5853d3d0ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28335,
"upload_time": "2025-08-07T08:33:02",
"upload_time_iso_8601": "2025-08-07T08:33:02.795886Z",
"url": "https://files.pythonhosted.org/packages/4e/74/a14690b545798ac3723e61a91d60518300eab0f5fba4616fd6c33eb1a57e/shadowai-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 08:33:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KevinZhang19870314",
"github_project": "shadowai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "agno",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "shadowai"
}
JSON
