Skip to main content

The official Python library of socra AI

Project description

socra

logo

🧬 Let your codebase improve itself with AI, from the command line.

Release Notes PyPI - License PyPI - Downloads GitHub star chart Open Issues X

Installation

First, install the library:

pip install socra

Next, be sure to set an OPENAI_API_KEY environment variable. socra currently uses OpenAI for LLM requests, but aim to add multiple providers in the near future. See OpenAI's docs if you don't yet have an API key.

🤔 What is socra?

socra is an open-source system for enabling rapid code mutation and improvement on any codebase from the command line using large language models (LLMs) and other AI application techniques.

Unlike other LLM-based approaches to software development, socra improves your code without the need to use a web-app, install a new editor, or use any other unergonomic interface. Code is mutated directly from the command line, freeing you up to use your favorite tools for the human part of software development.

socra aims to be an essential command line tool for you, as useful as your favorite version control system or native terminal commands.

Motivation

Biological Mutations

In biology, genetic mutation is the ultimate source of all genetic variation, and is the substrate on which evolution and natural selection act. Most mutations are relatively small in proportion to the overall genome of an organism, and may be beneficial, neutral, or harmful to the organism in a particular environment.

Selection pressure provides a probabilistic feedback mechanism for mutations providing some benefit to an organizm to persist across time. That is, over many iterations, genetic mutations providing some benefit to an organism in a particular environment tend to persist.

Through this process, genetic lineages form and give rise to earth's numerous species, each with its own genetic code and adaptations.

Current State of Software

There is quite a lot of code existing in the world, much of it quickly becoming dead weight and unuseful. Engineers typically love building new things, but rarely enjoy maintaining software for decades.

Some interesting stats about code repos:

socra as an Intelligent Replicator

With this biological and market backdrop, let's draw some comparisons to software code.

Until now, helpful mutations to code generally fall under the following categories:

  1. Human: (hopefully) intelligent human actors aiming to improve or add some functionality to a project they have a vested interest in, using any number of tools to ease the development process (text editors, extensions, conversational chat bots)
  2. Deterministic Bot: bots built to deterministically make some mutation. For example, a bot to automatically update project dependencies, format and lint code, run some tests, etc.

There also exist other ways to mutate code, like changing characters at random, but these types of changes are rarely productive and usually introduce errors and break code.

This project aims to introduce the following third method for generating helpful code mutations:

  1. socra: random (or targeted) intelligent code mutations introduced entirely by AI and verified only by humans.

Usage

From your favorite terminal, make sure socra is installed:

socra --version

To quickly improve any file or directory:

socra improve <path_to_target> "<instructions>"

# E.g.
socra improve ./src/main.py "Add docstrings to this file and clean it!"

Concepts

Node

A node represents an object in a hierarchy. node can have exactly one parent and zero or more children. Some node types can have children, and others can't (leaf nodes).

Action

An action is a functional unit with defined input and output parameters. Actions can implement regular functions, use AI, call other actions, or any combination thereof. In this way, actions are incredibly flexible functional units.

Capability

Capabilities strictly define one object's capabilities on another. For example, an agent may have differing capabilities based on its model type, the node it is interacting with, and other criteria. Capabilities start with can_.

API

An API is a set of rules that connect one application to another. In socra, an API is typically used to connect nodes, actions, and capabilities together internally.

Executor

Executors use APIs and an objective to work toward a goal.

For example, an agent executor can interact with a File API for a codebase in order to achieve an objective, perform some action, or instantiate another executor (one more suitable for the task at hand, for example)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

socra-0.0.9.tar.gz (28.0 kB view details)

Uploaded Source

Built Distribution

socra-0.0.9-py3-none-any.whl (41.4 kB view details)

Uploaded Python 3

File details

Details for the file socra-0.0.9.tar.gz.

File metadata

  • Download URL: socra-0.0.9.tar.gz
  • Upload date:
  • Size: 28.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for socra-0.0.9.tar.gz
Algorithm Hash digest
SHA256 61b1a83c48790b101bd485b489b728d2ba946f1221cdd4cdc53ef1abedfd2dcc
MD5 74599e5266fc6da94a75d6d272c256cf
BLAKE2b-256 2f1560ff868561f9f0c137159ffc1ab6b1e68f99794038fbe8a73c30f16c9151

See more details on using hashes here.

Provenance

The following attestation bundles were made for socra-0.0.9.tar.gz:

Publisher: _release.yml on socra/socra-python

Attestations:

File details

Details for the file socra-0.0.9-py3-none-any.whl.

File metadata

  • Download URL: socra-0.0.9-py3-none-any.whl
  • Upload date:
  • Size: 41.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for socra-0.0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 6f4aedced3f97e523ec283cd6471252b292271cbc81ce83c04649337522b2607
MD5 2e45bb037bd361ee0fa5929e7f1a4897
BLAKE2b-256 b094702f0a3e5c7988394f0e74aa58d2344a1ae57d75fd785f077e0b3bad11f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for socra-0.0.9-py3-none-any.whl:

Publisher: _release.yml on socra/socra-python

Attestations:

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page