intellibricks 0.10.5
IntelliBricks provides a streamlined set of tools for developing AI-powered applications. It simplifies complex tasks such as interacting with LLMs, training machine learning models, and implementing Retrieval Augmented Generation (RAG). Focus on building your application logic, not wrestling with boilerplate. IntelliBricks empowers you to build intelligent applications faster and more efficiently.
Requires Python: >=3.13.0

<p align="center">
  <img src="/docs/_static/logo.png" alt="Logo" width="400" />
</p>



<h1 align="center">Start Building Intelligence</h1>

<p align="center">
  <b>The Python-first Framework for Agentic & LLM-Powered Applications</b>
</p>

---

**Stop wrestling with AI boilerplate. Start building intelligence.**

IntelliBricks is the **Python-first toolkit** for crafting AI applications with ease. Focus on your *intelligent logic*, not framework complexity.

![Quick Overview](/docs/_static/quick_overview.svg)

**Imagine this:**

*   **Pythonic AI:** Write clean, intuitive Python – IntelliBricks handles the AI plumbing.
*   **Structured Outputs, Instantly:** msgspec.Struct classes define your data, IntelliBricks gets you structured LLM responses.
*   **Agents that Understand:** Build autonomous agents with clear tasks, instructions, and your knowledge.
*   **APIs in Minutes:**  Deploy agents as REST APIs with FastAPI or Litestar, effortlessly.
*   **Context-Aware by Default:** Seamless RAG integration for informed, intelligent agents.

**IntelliBricks solves AI development pain points:**

*   **Complexity? Gone.** Streamlined, Python-first approach.
*   **Framework Chaos? Controlled.** Predictable, structured outputs with Python types.
*   **Boilerplate? Banished.** Focus on intelligence, predictability and observability. No more time setting the framework up.

**Start in Seconds:**

```bash
pip install intellibricks
```

---

## Core Modules: Your AI Building Blocks

IntelliBricks is built around three core modules, designed for power and seamless integration:

### 🧠 LLMs Module: Integrate easilly with AI providers

Interact with Language Models in pure Python.

**Key Features:**

*   **Synapses:** Connect to Google Gemini, OpenAI, Groq, and more with one line of code.

    ```python
    from intellibricks.llms import Synapse

    synapse = Synapse.of("google/genai/gemini-pro-experimental")
    completion = synapse.complete("Write a poem about Python.") # ChatCompletion[RawResponse]
    print(completion.text)
    ```

*   **Structured Outputs:** Define data models with Python classes using `msgspec.Struct`.

    ```python
    import msgspec
    from typing import Annotated, Sequence
    from intellibricks.llms import Synapse

    class Summary(msgspec.Struct, frozen=True):
        title: Annotated[str, msgspec.Meta(title="Title", description="Summary Title")]
        key_points: Annotated[Sequence[str], msgspec.Meta(title="Key Points")]

    synapse = Synapse.of("google/genai/gemini-pro-experimental")
    prompt = "Summarize quantum computing article: [...]"
    completion = synapse.complete(prompt, response_model=Summary) # ChatCompletion[Summary]

    print(completion.parsed.title)
    print(completion.parsed.key_points)
    ```

*   **Chain of Thought:** Structured reasoning with `ChainOfThought` for observability.

    ```python
    from intellibricks.llms import Synapse, ChainOfThought
    import msgspec

    class Response(msgspec.Struct):
        response: str
        """just to show you can combine ChainOfThought and other structured classes too"""

    synapse = Synapse.of("google/genai/gemini-pro-experimental")
    cot_response = synapse.complete(
        "Solve riddle: Cities, no houses...",
        response_model=ChainOfThought[Response] # You can use ChainOfThoughts[str] too!
    ) 

    for step in cot_response.parsed.steps:
        print(f"Step {step.step_number}: {step.explanation}")

    print(cot_response.parsed.final_answer) # Response
    ```

*   **Langfuse Observability:** Built-in integration for tracing and debugging.

    ```python
    from intellibricks.llms import Synapse
    from langfuse import Langfuse

    synapse = Synapse.of(..., langfuse=Langfuse())
    ```
    ![Langfuse](static/readme_images/langfuse_view.jpeg)

### 🤖 Agents Module: Build Autonomous Intelligence

Craft agents to perform complex tasks.

**Key Features:**

*   **Agent Class:** Define tasks, instructions, and connect to Synapses.

    ```python
    from intellibricks.agents import Agent
    from intellibricks.llms import Synapse

    synapse = Synapse.of("google/genai/gemini-pro-experimental")
    agent = Agent(
        task="Creative Title Generation",
        instructions=["Intriguing fantasy story titles."],
        metadata={"name": "TitleGen", "description": "Title Agent"},
        synapse=synapse,
    )

    agent_response = agent.run("Knight discovers dragon egg.") # AgentResponse[RawResponse]
    print(f"Agent suggests: {agent_response.text}")
    ```

*   **Tool Calling:** Equip agents with tools for real-world interaction.
*   **Instant APIs:** Turn agents into REST APIs with FastAPI/Litestar.

    ```python
    from intellibricks.agents import Agent
    from intellibricks.llms import Synapse
    import uvicorn

    agent = Agent(..., synapse=Synapse.of(...))
    app = agent.fastapi_app # WIP, any bugs open an issue please!
    uvicorn.run(app, host="0.0.0.0", port=8000)
    ```

---

## 🏆 Why IntelliBricks? Python Purity & Power.

IntelliBricks is different. It's **Python First.**

*   🐍 **Idiomatic Python:**  Clean, modern Python – no framework jargon.
*   ✨ **Simplicity & Clarity:** Intuitive API, less boilerplate.
*   🧱 **Structured Outputs, Core Strength:** Define Python classes, get structured data.
*   🧠 **Focus on Intelligence:** Build smart apps, not infrastructure headaches.

---

## Structured Outputs: IntelliBricks vs. LangChain & LlamaIndex

Getting structured data from LLMs is critical. Here's how IntelliBricks compares to other frameworks:

**IntelliBricks:**

```python
import msgspec
from intellibricks.llms import Synapse

class Summary(msgspec.Struct, frozen=True):
    title: str
    key_points: list[str]

synapse = Synapse.of("google/genai/gemini-pro-experimental")
completion = synapse.complete(
    "Summarize article: [...]",
    response_model=Summary
) # ChatCompletion[Summary]

print(completion.parsed) # Summary object
```

**LangChain:**

```python
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field
from typing import Optional

class Joke(BaseModel):
    setup: str = Field(description="The setup of the joke")
    punchline: str = Field(description="The punchline to the joke")
    rating: Optional[int] = Field(default=None, description="Rating 1-10")

llm = ChatOpenAI(model="gpt-4o-mini")
structured_llm = llm.with_structured_output(Joke)
joke = structured_llm.invoke(
    "Tell me a joke about cats"
) # Dict[Unknown, Unknown] | BaseModel

print(joke) # Joke object directly
```

*LangChain uses `.with_structured_output()` and Pydantic classes. While functional, it relies on Pydantic for validation and returns the Pydantic object directly via `.invoke()`, losing direct access to completion metadata (usage, time, etc.)*

**LlamaIndex:**

```python
from llama_index.llms.openai import OpenAI
from pydantic import BaseModel, Field
from datetime import datetime
import json

class Invoice(BaseModel):
    invoice_id: str = Field(...)
    date: datetime = Field(...)
    line_items: list = Field(...)

llm = OpenAI(model="gpt-4o")
sllm = llm.as_structured_llm(output_cls=Invoice)
response = llm.complete("...") # CompletionResponse

```

*Here is what LlamaIndex' returns:*
```py
class CompletionResponse(BaseModel):
    """
    Completion response.

    Fields:
        text: Text content of the response if not streaming, or if streaming,
            the current extent of streamed text.
        additional_kwargs: Additional information on the response(i.e. token
            counts, function calling information).
        raw: Optional raw JSON that was parsed to populate text, if relevant.
        delta: New text that just streamed in (only relevant when streaming).
    """

    text: str
    additional_kwargs: dict = Field(default_factory=dict)
    raw: Optional[Any] = None # Could be anything and could be None too. Nice!
    logprobs: Optional[List[List[LogProb]]] = None
    delta: Optional[str] = None
```

**IntelliBricks Advantage:**

*   **Python-First Purity:**  Clean, idiomatic Python.
*   **Simpler Syntax:** More direct and intuitive structured output definition.
*   **Blazing Fast:** Leverages `msgspec` for high-performance serialization, outperforming Pydantic.
*   **Comprehensive Responses:**  `synapse.complete()` returns `ChatCompletion[RawResponse | T]` objects, providing not just parsed data but also full completion details (usage, timing, etc.).

*Examples adapted from LangChain [docs](https://python.langchain.com/docs/how_to/structured_output/) and LlamaIndex [docs](https://docs.llamaindex.ai/en/stable/understanding/extraction/structured_llms/). IntelliBricks offers a more streamlined and efficient Python-centric approach.*

---

## 🚀 Join the IntelliBricks Revolution!

Build intelligent applications, the Python way.

*   **Get Started:** `pip install intellibricks`
*   **Explore:** Dive into the [documentation](https://arthurbrenno.github.io/intellibricks/).
*   **Contribute:**  It's community-driven!
*   **Connect:**  Share feedback and ideas!

Let's build the future of intelligent applications, together!