Metadata-Version: 2.4
Name: StringDALE
Version: 0.4.1
Summary: String Diagram Agent Language Express (StringDALE) is a language for building LLM agents using string diagrams.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: chromadb>=1.0.15
Requires-Dist: deepmerge>=2.0
Requires-Dist: fastcore>=1.8.5
Requires-Dist: google-search-results>=2.4.2
Requires-Dist: graphviz>=0.21
Requires-Dist: html2text>=2025.4.15
Requires-Dist: instructor>=1.10.0
Requires-Dist: ipython>=8
Requires-Dist: isodate>=0.7.2
Requires-Dist: jinja2>=3.1.6
Requires-Dist: joblib>=1.5.1
Requires-Dist: lark>=1.2.2
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: networkx>=3.3
Requires-Dist: openai>=1.97.1
Requires-Dist: pandas>=2.3.1
Requires-Dist: parse>=1.20.2
Requires-Dist: pillow>=11.3.0
Requires-Dist: prettyprint>=0.1.5
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: python-git>=2018.2.1
Requires-Dist: singleton-decorator>=1.0.0
Requires-Dist: smolagents>=1.20.0
Requires-Dist: sqlmodel>=0.0.24
Requires-Dist: wikipedia>=1.4.0
Description-Content-Type: text/markdown

# StringDALE


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

> String Diagram Agent Language Express (StringDale) is a library for
> building complex LLM agentic workflows easily using [string
> diagrams](https://julesh.com/the-art-of-string-diagrams/).

## Motivation

We found current agentic frameworks unnecessarily complex:

- Too many levels of abstractions and boilerplate code.
- Too many interfaces to learn
- To many wrappers to build for our code to fit these frameworks

As a response, we create stringdale which aims to:

- Have a small interface - making it easier to learn.
- Non-intrusive - You can use your own functions in stringdale, without
  fitting them to a complex interface.
- Have few levels of abstraction - we don’t create tons of wrappers you
  have to navigate, you bring your own functions and understand exactly
  what is happening at all times.
- Make tracing and debugging simple.

## Installation

``` bash
# in an environment with python>=3.10
pip install stringdale
```

`stringdale` uses [graphviz](https://graphviz.org) to draw your diagrams
in jupyter notebooks.

Make sure you [download and install](https://graphviz.org/download/)
graphviz on your system if you want diagrams to be rendered.

## Usage

Lets look at how to build a RAG workflow

``` python
# bring your own LLM based functions
# These can be any function or callable
# for now lets use example ones
from stringdale.chat import Chat
from stringdale.db import ChromaClient
```

Lets make an example vector db:

``` python
chroma_client = ChromaClient()

dog_docs = [
    {
        'id': 'dog1',
        'text': 'The Golden Retriever is a friendly, intelligent breed known for its golden coat. They make excellent family pets and are great with children.',
        'metadata': {'breed': 'Golden Retriever'}
    },
    {
        'id': 'dog2', 
        'text': 'German Shepherds are loyal, protective dogs often used in police work. They are highly trainable and good at various tasks.',
        'metadata': {'breed': 'German Shepherd'}
    },
    {
        'id': 'dog3',
        'text': 'The Golden Retriever is a friendly, intelligent breed with a beautiful golden coat. They are wonderful family pets that get along well with kids.',
        'metadata': {'breed': 'Golden Retriever'}  
    },
    {
        'id': 'dog4',
        'text': 'Huskies are energetic working dogs bred for cold climates. They have thick fur and often blue eyes.',
        'metadata': {'breed': 'Husky'}
    },
    {
        'id': 'dog5',
        'text': 'Siberian Huskies are active working dogs that thrive in cold weather. They are known for their thick coats and striking blue eyes.',
        'metadata': {'breed': 'Husky'} 
    }
]

chroma_client.add_collection("dog_docs",exists_ok=True)
chroma_client.upsert(collection_name="dog_docs",docs=dog_docs)
chroma_client.list(collection_name='dog_docs')
```

    [{'id': 'dog1',
      'text': 'The Golden Retriever is a friendly, intelligent breed known for its golden coat. They make excellent family pets and are great with children.',
      'metadata': {'breed': 'Golden Retriever'},
      'embedding': array([0.05813659, 0.02785078, 0.00372152, ..., 0.0241031 , 0.04067278,
             0.00027733])},
     {'id': 'dog2',
      'text': 'German Shepherds are loyal, protective dogs often used in police work. They are highly trainable and good at various tasks.',
      'metadata': {'breed': 'German Shepherd'},
      'embedding': array([ 0.03066194,  0.00074497,  0.01366658, ..., -0.0081617 ,
             -0.02541033, -0.01031713])},
     {'id': 'dog3',
      'text': 'The Golden Retriever is a friendly, intelligent breed with a beautiful golden coat. They are wonderful family pets that get along well with kids.',
      'metadata': {'breed': 'Golden Retriever'},
      'embedding': array([0.04065013, 0.02587523, 0.01385626, ..., 0.02761683, 0.03554016,
             0.00553581])},
     {'id': 'dog4',
      'text': 'Huskies are energetic working dogs bred for cold climates. They have thick fur and often blue eyes.',
      'metadata': {'breed': 'Husky'},
      'embedding': array([-0.02400597, -0.00190817, -0.02052087, ..., -0.02349378,
             -0.04244469, -0.02794758])},
     {'id': 'dog5',
      'text': 'Siberian Huskies are active working dogs that thrive in cold weather. They are known for their thick coats and striking blue eyes.',
      'metadata': {'breed': 'Husky'},
      'embedding': array([-0.01651848,  0.00581224, -0.02498457, ..., -0.00659932,
             -0.03063537, -0.02282516])}]

``` python
rag_chat = Chat(
    model='gpt-4o-mini',
    messages=[
        {'role':'system','content':'''
            You are a helpful assistant that answers questions about dogs.
            I found the following documents that may be relevant to the user's question:
            {% for doc in docs %}
            {{doc['text']}}
            {% endfor %}
            '''},
        {'role':'user','content':'{{question}}'},
    ]
)
```

``` python
# import the basic building blocks
from stringdale import V,E,Define
```

``` python
# define your diagram schema
with Define('hello world') as RAG:
    V('get_docs',chroma_client.query)
    E('Start->get_docs(**)')
        
    V('chat',rag_chat)
    E('get_docs->chat(docs=.)')
    E('Start->chat(question=query)')
    E('chat->End')

RAG.draw()
```

![](index_files/figure-commonmark/cell-6-output-1.svg)

``` python
# run the diagram
diagram = RAG()

diagram_input = {
    'query':'tell me some stuff about golden retrievers',
    'collection_name':'dog_docs',
    'k':2
}

for trace in diagram.run(diagram_input):
    # you can write any logging,tracing logic here
    trace.pprint(file='log_file.txt')
    pass

# after running, access the output 
diagram.output
```

    {'role': 'assistant',
     'content': 'The Golden Retriever is a friendly and intelligent breed known for its beautiful golden coat. They make excellent family pets and are particularly good with children, making them wonderful companions for families.',
     'meta': {'input_tokens': 198, 'output_tokens': 42}}

``` python
! cat log_file.txt
! rm log_file.txt
```

    Node Start:
    { 'input': { 'collection_name': 'dog_docs',
                 'k': 2,
                 'q': 'tell me some stuff about golden retrievers'},
      'output': { 'collection_name': 'dog_docs',
                  'k': 2,
                  'q': 'tell me some stuff about golden retrievers'}}
    ================================================================================
    Node Start:
    { 'input': { 'collection_name': 'dog_docs',
                 'k': 2,
                 'query': 'tell me some stuff about golden retrievers'},
      'output': { 'collection_name': 'dog_docs',
                  'k': 2,
                  'query': 'tell me some stuff about golden retrievers'}}
    ================================================================================
    Node get_docs:
    { 'input': { 'collection_name': 'dog_docs',
                 'k': 2,
                 'query': 'tell me some stuff about golden retrievers'},
      'output': [ { 'distance': 0.6993070840835571,
                    'id': 'dog3',
                    'metadata': {'breed': 'Golden Retriever'},
                    'text': 'The Golden Retriever is a friendly, intelligent breed '
                            'with a beautiful golden coat. They are wonderful '
                            'family pets that get along well with kids.'},
                  { 'distance': 0.7122190594673157,
                    'id': 'dog1',
                    'metadata': {'breed': 'Golden Retriever'},
                    'text': 'The Golden Retriever is a friendly, intelligent breed '
                            'known for its golden coat. They make excellent family '
                            'pets and are great with children.'}]}
    ================================================================================
    Node chat:
    { 'input': { 'docs': [ { 'distance': 0.6993070840835571,
                             'id': 'dog3',
                             'metadata': {'breed': 'Golden Retriever'},
                             'text': 'The Golden Retriever is a friendly, '
                                     'intelligent breed with a beautiful golden '
                                     'coat. They are wonderful family pets that '
                                     'get along well with kids.'},
                           { 'distance': 0.7122190594673157,
                             'id': 'dog1',
                             'metadata': {'breed': 'Golden Retriever'},
                             'text': 'The Golden Retriever is a friendly, '
                                     'intelligent breed known for its golden coat. '
                                     'They make excellent family pets and are '
                                     'great with children.'}],
                 'question': 'tell me some stuff about golden retrievers'},
      'output': { 'content': 'The Golden Retriever is a friendly and intelligent '
                             'breed known for its beautiful golden coat. They make '
                             'excellent family pets and are particularly good with '
                             'children, making them wonderful companions for '
                             'families.',
                  'meta': {'input_tokens': 198, 'output_tokens': 42},
                  'role': 'assistant'}}
    ================================================================================
    Node End:
    { 'input': { 0: { 'content': 'The Golden Retriever is a friendly and '
                                 'intelligent breed known for its beautiful golden '
                                 'coat. They make excellent family pets and are '
                                 'particularly good with children, making them '
                                 'wonderful companions for families.',
                      'meta': {'input_tokens': 198, 'output_tokens': 42},
                      'role': 'assistant'}},
      'output': { 'content': 'The Golden Retriever is a friendly and intelligent '
                             'breed known for its beautiful golden coat. They make '
                             'excellent family pets and are particularly good with '
                             'children, making them wonderful companions for '
                             'families.',
                  'meta': {'input_tokens': 198, 'output_tokens': 42},
                  'role': 'assistant'}}
    ================================================================================

## Reporting Bugs

Found bugs? Missing features? Feel free to [open an
issue](https://github.com/DeanLight/stringdale/issues)

## Contributing

Want to contribute to stringdale? Great! Feel free to submit a PR or
discuss a feature you would like to add in the Issues.

To get a working development environment:

``` bash
# clone the repo
git clone https://github.com/DeanLight/stringdale.git    
cd stringdale

# install stringdale in editable dev mode
pip install -e ".[dev]"

# run pre-commit to install commit hooks
pre-commit install
```

`stringdale` is developed using [nbdev](https://nbdev.fast.ai/)

``` bash
# Make changes under nbs/ directory
# ...

# clean and export notebooks into a python library
nbdev_clean && nbdev_export

# make sure tests pass
nbdev_test

# Changing the docs? make sure that they are rendering correctly
nbdev_docs
```
