automata.readthedocs.io

Automata is an evolving, fully autonomous, self-programming AI system that uses large language models such as GPT-4 together with a vector database to document, search, and write code. Its core capabilities are presented in order of increasing complexity: embeddings, code and documentation generation, indexing with SCIP indices, execution, and the Automata Agent. Each feature builds on the ones before it, and each has associated examples and API documentation in the project docs.

The Five Core Features

The documentation lists these features "in order of complexity," which is also a useful reading order:

How the features stack

The progression is cumulative rather than a menu of unrelated tools:

• Embeddings turn code into vectors, which is what makes semantic search over a codebase possible.
• Indexing adds SCIP indices for the search layer, giving the system structured code navigation alongside vector similarity.
• Code and documentation generation is where the system produces new code and docs; the docs describe this as forming the backbone of self-programming.
• Execution is the step where advanced coding tasks are actually carried out with downstream tooling.
• The Automata Agent sits at the top: it orchestrates instruction-following, from simple to non-trivial tasks, on top of the retrieval and generation layers below.

In short, embeddings and indexing supply the knowledge layer, generation supplies the writing layer, execution supplies the acting layer, and the agent ties them together.

Where to Find Guides and API Docs

The documentation points to several entry points:

• Setup guide — for installation and environment setup.
• Creating your own embeddings — a dedicated guide, including configuring the pyright-scip repository, updating code embeddings, and building and embedding the docs.
• Running your own agent — the Agent Guide, which documents OpenAIAutomataAgentConfigBuilder and OpenAIAutomataAgent.
• FAQ — a separate frequently-asked-questions page.
• Module reference — auto-generated module docs covering areas such as agent, cli, code_handling, code_parsers, code_writers, config, context_providers, core, embedding, eval, experimental, github_management, llm, memory_store, navigation, retrievers, symbol, symbol_embedding, tasks, tests, and tools.

A demo and a rough schematic diagram of the system are available on the project's GitHub page, which is also where installation, usage, and contribution information lives.

Practical Notes Before You Start

• The docs note that the module documentation is auto-generated via the run-doc-embedding pipeline and is still a work in progress, so expect gaps in the reference pages.
• The project asks readers to review its contribution guidelines and code of conduct before contributing.
• The documentation describes the system's ambitions (self-programming, a path toward AGI) but does not publish pricing or access details on the pages summarized here; check the setup guide and GitHub for current requirements.

If you are new to the project, the natural path is the setup guide first, then the embeddings guide, then the Agent Guide — following the same order in which the features themselves build on each other.

Automata's documentation lists "Creating Your Own Embeddings" as a dedicated guide, and the embedding pipeline is what turns the Automata codebase and its docs into searchable vectors. To create your own, you work through three documented stages: configure the pyright-scip repository, update the code embeddings, then build and embed the docs. The page does not publish exact commands, so treat the steps below as the documented sequence to follow alongside the module docs rather than a copy-paste script.

What embeddings do in Automata

Automata describes itself as a self-programming AI system that uses large language models and a vector database to document, search, and write code. Embeddings are the bridge: code and documentation are converted into vectors so the system can retrieve relevant material during search and code generation. The docs list Embeddings first among the core features "in order of complexity," followed by code and documentation generation, indexing, execution, and the agent.

Two related pieces sit around the embedding step:

• Indexing — tutorials on creating and using SCIP indices for Automata Search.
• Symbol and symbol_embedding modules — listed in the module navigation, indicating embeddings are also maintained at the symbol level.

Prerequisites

• A local Automata environment set up per the setup guide ("Create Local Environment").
• Access to the pyright-scip repository, since the first documented step is configuring it.
• The embedding module documentation open, because the site notes module docs are auto-generated via the run-doc-embedding pipeline and still "a work in progress."

Step 1: Configure the pyright-scip repository

The "Creating Your Own Embeddings" page names this as the first task. pyright-scip is the indexing layer that produces SCIP data for the codebase; configuring it is what allows code to be analyzed before embedding. Follow the linked instructions on that page for the repository setup, and confirm the configuration works before moving on — later steps depend on it.

Step 2: Update the code embeddings

With indexing configured, the next documented task is updating the code embeddings. This regenerates vectors for the Automata interpreter codebase so search reflects current code. The Embeddings feature docs cover "how to generate code embeddings for Automata Interpreter codebase" and include associated examples and API documentation.

Expected result: an updated embedding set that the search and retrieval components can query. If results look stale after this step, the usual cause is that Step 1 was skipped or the index was not rebuilt — recheck the SCIP configuration first.

Step 3: Build and embed the docs

The third task is building and embedding the documentation. This mirrors the code path but for prose: docs are built, then embedded so they are retrievable alongside code. The site itself is generated this way — module documents are produced "via the run-doc-embedding pipeline," which is a useful reference point for what the output should look like.

Where the relevant docs live

Common sticking points

• Skipping the index step. Embeddings depend on the SCIP index produced from the configured pyright-scip repo; updating embeddings without it yields incomplete coverage.
• Expecting finished docs. The site explicitly warns module documentation is auto-generated and in progress, so some module pages may be thin. Use the feature-level guides and examples as the primary reference.
• Forgetting the docs half. Code embeddings alone leave documentation out of retrieval; run the build-and-embed docs step as well.

Once embeddings are in place, the natural next step is running an agent per the Agent Guide, which covers both trivial and non-trivial instruction execution.

Automata is an open documentation site for a self-programming AI system that uses large language models (the docs cite GPT-4) together with a vector database to document, search, and write code. The site is the project's documentation hub rather than a hosted product: it contains setup guides, feature guides, and auto-generated module references. It is relevant if you want to run or extend the system yourself; it is not a sign-up service, and the documentation does not describe pricing or a hosted offering.

What the project actually does

The documentation describes Automata as "an evolving, fully autonomous, self-programming Artificial Intelligence system." In practice, the documented capabilities break down into four layers, listed on the site in order of complexity:

• Embeddings — generating code embeddings for the Automata interpreter codebase, so code can be stored and retrieved by meaning rather than exact text.
• Code and documentation generation — the documented backbone of the "self-programming" claim: the system writes and documents code.
• Indexing — creating and using SCIP indices to power Automata Search.
• Execution and the agent — running an Automata agent that carries out coding tasks, from trivial to non-trivial instructions, using downstream tooling.

The vector database is the retrieval layer that connects these: code and docs are embedded and indexed, the agent searches them, and the LLM generates new code or documentation from what it finds.

What you'll find on the site

How to decide whether to dig in

The documentation is explicitly a work in progress — the module pages are auto-generated by a "run-doc-embedding pipeline," and the site asks readers to bear with it. That shapes who gets value from it:

• Worth exploring if you are comfortable setting up a local Python environment, want to experiment with an LLM-plus-vector-database coding agent, or want to study how code embeddings and SCIP indexing are wired into an agent loop.
• Probably not what you need if you want a ready-to-use coding assistant with an account and a web interface — the docs describe a self-hosted project, not a managed service.

Before relying on it, read the contribution guidelines and code of conduct linked from the homepage, since the project expects contributors to follow them.

A realistic first pass

A concrete way to test whether Automata fits your needs: follow the setup guide to create a local environment, then work through "Creating Your Own Embeddings" — configuring pyright-scip, updating code embeddings, and building and embedding the docs. If that pipeline runs end to end, you have the retrieval layer the agent depends on, and you can move on to the Agent Guide to run a simple instruction. If the setup stalls, the FAQ is the documented place to check first.

Automata is an open-source, self-programming AI system that uses large language models (such as GPT-4) and a vector database to document, search, and write code. To get it running, follow the project's setup guide to create a local environment and install dependencies, then configure an agent with OpenAIAutomataAgentConfigBuilder and run it through the agent CLI with a simple instruction to confirm everything works. The steps below reflect what the documentation currently covers; because the docs are described as a work in progress, expect some sections to be thin.

Prerequisites

• A local development environment where you can install Python dependencies (the setup guide is titled "Create Local Environment").
• Access to an LLM provider. The documentation's agent configuration centers on OpenAI models like GPT-4, so plan on having an OpenAI-compatible API credential available.
• Basic familiarity with running CLI commands and editing configuration files.

The documentation does not publish pricing or account-tier details for Automata itself, so treat any provider costs as coming from your LLM API usage rather than from Automata.

Step 1: Create the local environment

Start from the project's setup guide, which walks through creating a local environment and installing dependencies. In practice this means:

1. Clone the repository from the GitHub page linked in the docs.
2. Create and activate a virtual environment.
3. Install the project's dependencies.

Expected result: an activated environment where the automata package and its CLI are importable. Common snag: the docs note that module documentation is auto-generated via the run-doc-embedding pipeline and still incomplete, so if a dependency step is ambiguous, cross-check against the repository's own install files rather than the rendered docs alone.

Step 2: Configure the agent

Agent behavior is configured through OpenAIAutomataAgentConfigBuilder, documented under the Agent Guide alongside OpenAIAutomataAgent. The builder is where you supply the model and agent settings before constructing the agent. You will also need your provider credentials available to the process (typically via environment variable, per your provider's convention).

A minimal configuration pattern looks like this:

from automata.agent import OpenAIAutomataAgentConfigBuilder, OpenAIAutomataAgent

config = (
    OpenAIAutomataAgentConfigBuilder()
    .with_model("gpt-4")          # model name per your provider
    .build()
)

agent = OpenAIAutomataAgent(config=config)

Check the Agent Guide page for the exact builder methods your installed version exposes — the documentation lists the classes but the auto-generated module pages are the authoritative reference for method names.

Step 3: Run the agent CLI with a simple instruction

The docs list an agent CLI entry point under the setup section. Use it to run a trivial instruction first, so a failure is easy to isolate:

automata agent "List the files in the current directory and summarize what this project does"

Expected result: the agent accepts the instruction, calls the model, and returns a response or tool action. Common snags:

• Missing credentials: the agent will fail at the first model call. Confirm your API key is exported in the same shell.
• Import or path errors: usually mean the environment from Step 1 isn't active.
• Empty or partial output: the docs describe the agent as capable of both trivial and non-trivial instruction execution; start trivial and scale up only after a clean run.

Step 4: Verify and extend

Once a trivial instruction succeeds, you have a working baseline. From there the documented feature path runs roughly in order of complexity:

If you want the agent to search your own code, the "Creating Your Own Embeddings" guide covers configuring the pyright-scip repository, updating code embeddings, and building and embedding the docs. The FAQ page is the place to check when a step behaves differently from the guide.

When this approach fits

This setup path suits developers who want to run Automata locally and experiment with an autonomous coding agent on their own machine. If you only need to read about the architecture, the GitHub page hosts a demo and a rough schematic diagram — no installation required. Because the documentation is explicitly still being completed, budget time for cross-referencing the repository when a guide step is missing.

Automata's documentation is organized into a small set of entry points, and the fastest route depends on what you're trying to do. Setup, agent usage, embeddings, indexing, and execution each have their own guide; the FAQ and GitHub page cover common questions and the demo; contribution guidelines and the code of conduct are linked from the main documentation page. The sections below map each task to the right place.

Documentation Map by Task

Core Feature Guides

The main page lists features "in order of complexity," which is a useful reading order if you're new:

1. Embeddings — how to generate code embeddings for the Automata interpreter codebase.
2. Code and Documentation Generation — the backbone of Automata's self-programming ability.
3. Indexing — creating and using SCIP indices for Automata Search.
4. Execution — running advanced coding tasks via downstream tooling.
5. Automata Agent — running an agent, including trivial and non-trivial instruction execution.

If your goal is simply to get something running, start with Setup and then the Agent Guide; the embeddings and indexing material matters mainly once you want the system to search and write code against a codebase.

Embeddings, Indexing, and Module References

The embeddings guide is split into concrete steps rather than a single page: configure the pyright-scip repository, update the code embeddings, then build and embed the docs. The module documentation (covering areas such as agent, cli, code_handling, code_parsers, code_writers, config, context_providers, core, embedding, eval, github_management, llm, memory_store, navigation, retrievers, symbol, symbol_embedding, tasks, tests, and tools) is auto-generated via the run-doc-embedding pipeline. The documentation itself notes it is still a work in progress, so expect gaps in module-level pages and treat the feature guides as the more reliable reference.

FAQ, Demo, and Live Status

The FAQ is the place to check before filing an issue. For a demo and a rough schematic diagram of the system, the documentation points to the GitHub page, which also covers installation, usage, and contribution details. A "Live Status" section exists on the main page but the provided material doesn't specify what it displays, so check it directly rather than assuming.

Contributing

Before opening a pull request, read the contribution guidelines and adhere to the code of conduct, both linked from the main documentation page. These are stated as requirements, not suggestions.

Practical Notes

• The documentation is explicitly labeled a work in progress; if a module page is thin, fall back to the feature guides or the GitHub repository.
• Setup is the prerequisite for everything else — the agent, embeddings, and indexing guides assume a working local environment.
• The main page does not state pricing or licensing terms for using Automata, so don't infer cost or access conditions from the documentation alone.