Metadata-Version: 2.4
Name: christofy
Version: 1.1.0
Summary: Christofy is a lightweight, modular PyTorch-based AI toolkit that unifies essential deep learning capabilities. It supports Image Classification, Segmentation, and advanced Vision Analysis with clean, easy-to-use APIs. With built-in Retrieval-Augmented Generation (RAG) powered by ChromaDB and Ollama, it seamlessly blends vision and language intelligence. Designed for flexibility and speed, Christofy is your all-in-one arsenal for building modern AI solutions.
Author-email: Aswin Christo <aswinchristo17@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/aswinchristo/christofy
Project-URL: Bug Tracker, https://github.com/aswinchristo/christofy/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Christofy 🧠📦✨

**Christofy** is a comprehensive AI toolkit that combines deep learning, computer vision, and intelligent agent capabilities. Built on PyTorch and integrated with modern LLMs, it provides everything you need for image classification, vision analysis, document understanding, and building intelligent AI agents.

---

## 🚀 Features

### Core Capabilities
- ✅ **Image Classification**: Train CNN classifiers (ResNet18) for binary and multi-class tasks
- ✅ **Vision Analysis**: Multimodal AI for image understanding with Ollama integration
- ✅ **RAG Pipeline**: Retrieval-Augmented Generation for document analysis
- ✅ **Image Segmentation**: Graph-based segmentation with customizable parameters
- ✅ **AutoML**: Automated machine learning for tabular data
- ✅ **AI Agents**: Build intelligent agents with custom tools, memory, and personality (NEW in v1.1.0)

### Agent Features (v1.1.0)
- 🤖 **Multi-LLM Support**: OpenAI, Claude, Gemini, and Groq
- 🔧 **Custom Tools**: Register any Python function as an agent tool
- 🧠 **Memory System**: Short-term conversation memory
- 🎭 **Personalities**: Pre-built templates (teacher, researcher, coder, etc.)
- 🔍 **Web Search**: Built-in DuckDuckGo integration
- 📚 **RAG Integration**: Query documents and knowledge bases
- ⚡ **Async Support**: Run tools asynchronously

### Supported File Formats
- Images: JPG, PNG, BMP, and more
- Documents: PDF, DOCX, TXT, JSON
- Data: CSV, Excel (XLSX, XLS)

---

## 📦 Installation

```bash
pip install christofy
```

### Optional Dependencies

For PDF support:
```bash
pip install PyPDF2  # or pdfplumber
```

For DOCX support:
```bash
pip install python-docx
```

For agent web search:
```bash
pip install ddgs
```

For agent LLM support:
```bash
pip install openai anthropic google-generativeai groq
```

For .env file support (recommended):
```bash
pip install python-dotenv
```

---

## 📚 Usage

### 🤖 AI Agents (NEW in v1.1.0)

Build intelligent agents with custom tools, memory, and personality in just a few lines!

#### Basic Agent

```python
from christofy.agents import AgentBuilder

# Create a simple agent
agent = AgentBuilder()
agent.create(
    task="You are a helpful AI assistant",
    llm="openai:gpt-4o",  # or claude:sonnet, gemini:pro, groq:llama3
)

# Ask questions
response = agent.ask("Explain quantum computing in simple terms")
print(response)
```

#### Agent with Tools

```python
from christofy.agents import AgentBuilder, tool

# Define custom tools
@tool(name="calculator", description="Evaluate mathematical expressions")
def calculator(expression: str) -> str:
    """Calculate the result of a math expression."""
    try:
        result = eval(expression)
        return f"Result: {result}"
    except Exception as e:
        return f"Error: {e}"

@tool(name="word_count", description="Count words in a text")
def word_count(text: str) -> str:
    """Count the number of words in the given text."""
    count = len(text.split())
    return f"Word count: {count}"

# Create agent with tools and memory
agent = AgentBuilder()
agent.create(
    task="You are a helpful assistant with calculation and text analysis abilities",
    tools=["calculator", "word_count", "websearch"],  # Built-in + custom tools
    llm="openai:gpt-4o",
    memory=True,  # Enable conversation memory
    temperature=0.7
)

# Use the agent
print(agent.ask("What is 125 * 847?"))
print(agent.ask("Count the words in: The quick brown fox jumps"))
print(agent.ask("Search for the latest AI news"))
```

#### Agent with Personality

```python
from christofy.agents import AgentBuilder, list_personalities

# See available personalities
print(list_personalities())
# ['default', 'teacher', 'researcher', 'coder', 'assistant', 'analyst', 'creative']

# Create a teacher agent
agent = AgentBuilder()
agent.create(
    task="Help students learn programming",
    personality="teacher",
    llm="claude:sonnet",
    memory=True
)

response = agent.ask("How do loops work in Python?")
print(response)
```

#### Agent with RAG (Document Query)

```python
from christofy.agents import AgentBuilder

agent = AgentBuilder()
agent.create(
    task="You are a document analysis assistant",
    tools=["rag"],
    llm="openai:gpt-4o",
)

# Configure RAG with your documents
agent.configure_rag(data_path="./documents")  # folder, file, or raw text

# Query your documents
response = agent.ask("What are the key findings in the research papers?")
print(response)
```

#### Supported LLM Providers

```python
# OpenAI
agent.create(llm="openai:gpt-4o")      # GPT-4o
agent.create(llm="openai:gpt-4")       # GPT-4
agent.create(llm="openai:gpt-3.5")     # GPT-3.5 Turbo

# Claude (Anthropic)
agent.create(llm="claude:sonnet")      # Claude Sonnet 4.5
agent.create(llm="claude:opus")        # Claude Opus 4.5
agent.create(llm="claude:haiku")       # Claude Haiku 4.5

# Google Gemini
agent.create(llm="gemini:pro")         # Gemini 1.5 Pro
agent.create(llm="gemini:flash")       # Gemini 1.5 Flash

# Groq
agent.create(llm="groq:llama3")        # Llama 3 70B
agent.create(llm="groq:mixtral")       # Mixtral 8x7B
```

#### API Key Configuration

You can provide API keys in three ways:

**1. Using a .env file (Recommended)**

Create a `.env` file in your project root:
```bash
OPENAI_API_KEY=your-openai-key-here
ANTHROPIC_API_KEY=your-anthropic-key-here
GOOGLE_API_KEY=your-google-key-here
GROQ_API_KEY=your-groq-key-here
```

Install python-dotenv:
```bash
pip install python-dotenv
```

**2. Using environment variables**

```bash
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GOOGLE_API_KEY="your-key"
export GROQ_API_KEY="your-key"
```

**3. Directly in code**

```python
agent = AgentBuilder()
agent.create(
    task="You are a helpful assistant",
    llm="openai:gpt-4o",
    api_key="your-api-key-here"  # Pass directly
)
```

---

---

### 📸 Image Classification

```python
import christofy

# Train a model
christofy.train_model(
    data_dir="path/to/dataset",
    learning_rate=0.001,
    epochs=10,
    batch_size=32,
    output_dir="output"
)

# Make predictions
predicted_class = christofy.predict_image(
    model_path="output/model.pth",
    image_path="path/to/image.jpg"
)
```

---

### 🔍 RAG Pipeline (Retrieval-Augmented Generation)

```python
from christofy import run_rag_pipeline

# Example usage
response = run_rag_pipeline(
    data="path/to/documents",  # Can be file, directory, or text
    query="Your question here?",
    model="llama2",              # Your local Ollama model
    embedding_model="nomic-embed-text",  # For embeddings
    temperature=0.7
)

print(response)
```

**Supported File Formats:**
- PDF files (requires PyPDF2 or pdfplumber)
- Word documents (DOCX) (requires python-docx)
- CSV and Excel files (requires pandas)
- Text files (TXT)
- JSON files

---

### 👁️ Vision Analysis

```python
from christofy import vision_spell

# Basic usage
vision_spell("image.jpg", "What do you see?")

# With model selection
vision_spell("image.jpg", "What do you see?", model="llava:13b")

# Full parameters
vision_spell(
    image_path="image.jpg",
    question="What do you see?",
    model="llava",
    temperature=0.7,
    max_tokens=None,
    system_prompt=None,
    conversation_mode=False
)

# Conversation mode
chat = vision_spell("image.jpg", "What do you see?", conversation_mode=True)
chat.ask("What colors are present?")
chat.ask("Is this indoors or outdoors?")

# Export conversation
chat.export_conversation("json")
chat.export_conversation("txt")

# Batch processing
from christofy import batch_vision_analysis

batch_vision_analysis(
    image_paths=["img1.jpg", "img2.png"],
    questions="What do you see?",
    model="llava"
)

# Utility functions
from christofy import list_vision_models, get_system_info, show_module_info

# Alternative function name
from christofy import vision
vision("image.jpg", "What do you see?")
```

---

### 🎨 Image Segmentation

```python
from christofy import segmenter

# Basic usage with default parameters
segmenter("image.jpg")

# With custom parameters
segmenter(
    image_path="image.jpg",
    sigma=0.5,           # Standard deviation for Gaussian smoothing
    merge_threshold=500,  # Threshold for merging segments
    min_size=50          # Minimum segment size
)
```

---

### 🤖 Machine Learning for Tabular Data

```python
from christofy.ml import ml_trainer, ml_predictor

# Example 1: AutoML (automatic algorithm selection)
result1 = ml_trainer(
    data="data.csv",  # Replace with your CSV file
    target="target",  # Replace with your target column
    hyperparams={
        "test_size": 0.3,
        "cv": 5
    },
    save_path="automl_model.pkl"
)

# Example 2: User-specified algorithm
result2 = ml_trainer(
    data="data.csv",
    target="target",
    algorithm="random_forest",
    hyperparams={
        "test_size": 0.25,
        "cv": 10,
        "n_estimators": 200,
        "max_depth": 8
    },
    save_path="rf_model.pkl"
)

# Example 3: Make predictions
predictions = ml_predictor(
    model_path="automl_model.pkl",
    values=[[5.1, 3.5, 1.4, 0.2], [6.2, 2.8, 4.8, 1.8]]
)
```

**Supported Algorithms:**
- AutoML (automatic algorithm selection)
- Random Forest
- Gradient Boosting
- Support Vector Machines
- Logistic Regression
- K-Nearest Neighbors
- And more!

---

## 🔧 Requirements

### Core Dependencies
- Python 3.9+
- PyTorch
- Pillow (for image processing)
- NumPy

### Feature-Specific Dependencies
- **RAG & Vision**: Ollama (for local LLM inference)
- **Segmentation**: scikit-image, matplotlib
- **ML**: scikit-learn, pandas
- **Agents**: openai, anthropic, google-generativeai, groq (based on LLM provider)
- **Agent RAG**: chromadb, sentence-transformers, pypdf (for PDF support)
- **Web Search**: duckduckgo-search
- **Document Processing**: PyPDF2/pdfplumber (PDF), python-docx (Word), pandas (CSV/Excel)

---

## 🚀 Quick Start Examples

### Complete Agent Example

```python
from christofy.agents import AgentBuilder, tool

# Custom tool
@tool(name="get_weather", description="Get current weather for a city")
def get_weather(city: str) -> str:
    # In real scenario, call weather API
    return f"The weather in {city} is sunny, 72°F"

# Create and configure agent
agent = AgentBuilder()
agent.create(
    task="You are a helpful travel assistant",
    tools=["websearch", "get_weather"],
    personality="assistant",
    llm="openai:gpt-4o",
    memory=True,
    temperature=0.7
)

# Multi-turn conversation
print(agent.ask("What's the weather in Paris?"))
print(agent.ask("What are the top attractions there?"))
print(agent.ask("Based on the weather, what should I pack?"))
```

### Vision + RAG Pipeline

```python
from christofy import vision_spell, run_rag_pipeline

# Analyze an image
vision_response = vision_spell(
    "product_image.jpg",
    "Describe this product in detail",
    model="llava"
)

# Query related documentation
doc_response = run_rag_pipeline(
    data="./product_docs",
    query="What are the specifications of this product?",
    model="llama2"
)

print("Vision Analysis:", vision_response)
print("Documentation:", doc_response)
```

---

## 🎯 Use Cases

- **Chatbots & Virtual Assistants**: Build intelligent conversational agents
- **Research Assistants**: Agents that search the web and analyze documents
- **Code Helpers**: Programming assistants with personality and tools
- **Image Classification**: Train models for custom image recognition tasks
- **Document Analysis**: RAG for intelligent document querying
- **Vision AI**: Image understanding and multimodal analysis
- **Data Science**: AutoML for quick model prototyping

---

## 📖 API Reference

### Agent Methods

```python
agent = AgentBuilder()

# Configure the agent
agent.create(
    task: str,                    # System prompt/task description
    tools: list[str] = [],        # List of tool names
    llm: str = "openai:gpt-4o",  # LLM provider and model
    memory: bool = False,         # Enable conversation memory
    personality: str = "default", # Personality template
    temperature: float = 0.7,     # Response randomness (0-1)
    debug: bool = False          # Enable debug logging
)

# Interact with the agent
response = agent.ask(question: str) -> str

# Configure RAG (if using RAG tool)
agent.configure_rag(data_path: str)  # Path to file, folder, or raw text

# Get conversation history (if memory enabled)
history = agent.get_history() -> list[dict]

# Clear conversation memory
agent.clear_memory()

# Preview agent configuration
agent.preview()
```

### Tool Registration & Execution

```python
from christofy.agents import tool, list_tools, run_tool, run_tool_async

# Register a tool
@tool(name="my_tool", description="What the tool does")
def my_tool(arg1: str, arg2: int) -> str:
    return f"Result: {arg1} {arg2}"

# List all registered tools
tools = list_tools()

# 1. Run a tool manually (synchronously)
# If the tool is async, run_tool will automatically run it using asyncio.run()
result = run_tool("my_tool", arg1="test", arg2=42)

# 2. Run a tool manually (asynchronously)
# If the tool is sync, run_tool_async runs it in a thread pool to avoid blocking the event loop
result_async = await run_tool_async("my_tool", arg1="test", arg2=42)
```

#### Under the Hood Tool Execution Mechanics

The `run_tool` and `run_tool_async` functions act as a compatibility layer between sync and async contexts:

* **Sync Context Integration**: When working in a synchronous script, you can execute asynchronous tools safely with `run_tool()`.
* **Async Context Integration**: When building asynchronous systems (such as API servers or GUI loops), running synchronous tools can block the main execution thread. Calling `run_tool_async()` delegates sync tools to a thread pool via a background executor to prevent blocking.
* **Testing & Debugging**: Allows developers to isolate, test, and debug tool logic directly, completely bypassing the agent and saving LLM API costs.

---

## 🆕 What's New in v1.1.0

- 🤖 **AI Agent System**: Complete agent framework with tools, memory, and personalities
- 🔧 **Custom Tools**: Decorator-based tool registration system
- 🧠 **Multi-LLM Support**: OpenAI, Claude, Gemini, and Groq integration
- 🎭 **Personality System**: 7 pre-built personality templates
- 🔍 **Built-in Web Search**: DuckDuckGo integration for agents
- 📚 **RAG for Agents**: Document querying capabilities
- ⚡ **Async Tool Support**: Run tools asynchronously

---

## 💡 Advanced Examples

### Async Tools

```python
from christofy.agents import tool
import asyncio
import aiohttp

@tool(name="fetch_url", description="Fetch content from a URL asynchronously")
async def fetch_url(url: str) -> str:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()

agent = AgentBuilder()
agent.create(
    task="You are a web content analyzer",
    tools=["fetch_url"],
    llm="openai:gpt-4o"
)
```

### Combining Multiple Features

```python
from christofy import vision_spell, ml_trainer, segmenter
from christofy.agents import AgentBuilder, tool

# Image analysis tool
@tool(name="analyze_image", description="Analyze an image using vision AI")
def analyze_image(image_path: str) -> str:
    return vision_spell(image_path, "Describe this image in detail")

# Segmentation tool
@tool(name="segment_image", description="Segment an image into regions")
def segment_image(image_path: str) -> str:
    result = segmenter(image_path)
    return f"Image segmented into {result['num_segments']} regions"

# Create a vision-powered agent
agent = AgentBuilder()
agent.create(
    task="You are a computer vision assistant",
    tools=["analyze_image", "segment_image", "websearch"],
    llm="claude:sonnet",
    memory=True
)

print(agent.ask("Analyze photo.jpg and tell me what you see"))
print(agent.ask("Now segment it and describe the regions"))
```

---

## 🐛 Troubleshooting

### Agent Issues
- **API Key Errors**: Ensure environment variables are set (OPENAI_API_KEY, etc.)
- **Tool Not Found**: Check tool name spelling and registration
- **Memory Issues**: Memory is session-based, restart to clear

### Vision/RAG Issues
- **Ollama Connection**: Ensure Ollama is running (`ollama serve`)
- **Model Not Found**: Pull the model first (`ollama pull llava`)

### Installation Issues
- **Missing Dependencies**: Install optional packages as needed
- **PyTorch Issues**: Visit pytorch.org for platform-specific installation

---

## 📄 License

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

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

## 📞 Support

- GitHub Issues: [https://github.com/aswinchristo/christofy/issues](https://github.com/aswinchristo/christofy/issues)
- Documentation: See this README and inline code documentation

---

## ⭐ Star History

If you find Christofy useful, please consider giving it a star on GitHub!

---

**Made with ❤️ by Aswin Christo**
