Vector store extras, and one dependency pinned with ==

The manifest says fintech, the README says agents

There are two descriptions of this package and they do not match.

The README opens with Build Autonomous AI Agents in Python, and the Overview calls it a Python framework for building autonomous agents like OpenClaw and Claude Cowork, as well as more traditional agent systems.

The package metadata says something else:

description = "Agent Framework For Fintech"

So the distribution on PyPI describes a fintech framework while the repository describes an agent framework. Anyone who finds upsonic through a package search rather than through the repository sees the industry word first and has no way to tell from that line whether there is a domain restriction.

The rest of the metadata is conventional: name upsonic, version 0.77.3, two authors, MIT, and a floor of Python 3.10 or later with classifiers for 3.10, 3.11 and 3.12.

The version number is worth pausing on as well. A 0.77 line is a long way through a 0.x series, which suggests a project incrementing continuously rather than treating minor versions as milestones. The three newest releases are v0.77.3 from 2026-05-19, v0.77.2 from 2026-05-16 and v0.77.1 from 2026-05-15, three patch releases between 2026-05-15 and 2026-05-19, and the last push to the default branch, master, was on 2026-06-18.

Two agent classes, and only one of them has a workspace

There are two entry points and the difference is containment.

The traditional one is a model and a task:

from upsonic import Agent, Task

agent = Agent(model="anthropic/claude-sonnet-4-5", name="Stock Analyst Agent")

task = Task(description="Analyze the current market trends")

agent.print_do(task)

The autonomous one takes a workspace as well:

from upsonic import AutonomousAgent, Task

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-5",
    workspace="/path/to/logs"
)

task = Task("Analyze server logs and detect anomaly patterns")

agent.print_do(task)

And then one sentence that is the entire safety story: all file and shell operations are restricted to workspace, and path traversal and dangerous commands are blocked.

That is a much narrower claim than a sandbox, and the README is careful to say what it is not. For execution away from your machine it points at a next step rather than offering one: connect a Sandbox Provider such as E2B for isolated cloud execution environments.

So the choice is a directory boundary on your own machine, or a real sandbox elsewhere. There is no third option described here.

@tool reads the docstring, so the signature is the contract

Custom tools are ordinary Python functions with a decorator, and the tool contract is derived from the function rather than from a schema you write.

from upsonic.tools import tool

@tool
def sum_tool(a: float, b: float) -> float:

The docstring in the README's example is a Google-style block with Args and Returns sections, one line per argument, and that is the part the model reads to decide when to call the function. The type hints give the parameter and return types.

The task then carries the function:

task = Task(
    description="Calculate 15 + 27",
    tools=[sum_tool]
)

So the whole integration is three lines in the definition and one argument in the Task. There is no registry, no name mapping and no JSON schema to keep in sync.

The next step the README points at is MCP Tools, described as a way to connect your agents to thousands of external data sources and services. The optional dependency group behind it pulls mcp with its cli extra and fastmcp, so the MCP path is an extra rather than something in the core install.

OCR is two layers, and layer 0 is where the PDF becomes a picture

The OCR section is short and the architecture is worth reading, because the two layers exist for a reason.

Upsonic provides a unified OCR interface with a layered pipeline: Layer 0 handles document preparation, which it describes as PDF to image conversion and preprocessing, and Layer 1 runs the OCR engine.

That split is the point. An OCR engine takes an image, so anything that arrives as a PDF has to be rasterised first, and doing that inside the engine means every engine repeats it. Here you can swap the engine without touching the preparation.

You construct it in two lines:

from upsonic.ocr import OCR
from upsonic.ocr.layer_1.engines import EasyOCREngine

engine = EasyOCREngine(languages=["en"])
ocr = OCR(layer_1_ocr_engine=engine)

text = ocr.get_text("invoice.pdf")

The keyword argument is named layer_1_ocr_engine, so the layer boundary is visible in the constructor rather than implied.

The engines named are EasyOCR, RapidOCR, Tesseract, PaddleOCR, DeepSeek OCR, and DeepSeek via Ollama. That last one is the interesting entry: the same pipeline can end in a local model served by Ollama rather than in a traditional OCR library, and nothing in the interface changes. The extra is installed with uv pip install "upsonic[ocr]".

Nine vector stores behind nine extras, and one that installs several

The optional dependency groups are where the project's real scope is, and they are almost entirely storage.

There is chroma for chromadb, qdrant, milvus for pymilvus, weaviate, pinecone with pinecone-text, faiss for faiss-cpu with numpy, pgvector with psycopg, pgvector and sqlalchemy, supermemory, and asqav. Then mcp with fastmcp, which is the tool integration rather than storage.

So the storage backends each sit behind their own extra, and a group called vectordb that installs several of them together for the case where you want more than one.

Two entries carry version markers. chromadb is pinned to python_version below 3.14, and pinecone-text the same, so on a newer Python those extras install less than they would on 3.12 or 3.13.

The Makefile is what keeps that list honest. It has a test_storage_only target described as running only the storage tests and requiring docker-compose, a deps_smoke target that installs the optional deps for the smoke tests, storage and faiss, and a check_docker target that greps for a running service and starts docker_up if there is not one. docker_up waits for the services to be healthy by polling up to thirty times with a two second sleep between attempts, and every docker command tolerates both the docker-compose and the docker compose spelling.

psutil is the one exact pin in an otherwise floating list

The core dependency list has twenty entries and exactly one of them is pinned to an exact version.

    "psutil==6.1.1",
    "rich>=13.9.4",

Everything else in that list uses a floor: rich, sentry-sdk with the opentelemetry extra, toml, python-dotenv, uvicorn, nest-asyncio, pydantic and pydantic-core, typing-extensions, anyio, griffe, typing-inspection, httpx, aiohttp, requests, openai, genai-prices, cloudpickle. protobuf is the one with a ceiling, capped below 6.0.0.

Two entries explain what the framework is. openai at 2.2.0 or later means model calls go through an OpenAI-compatible client. And sentry-sdk with opentelemetry is a hard requirement, so error reporting and traces are wired into the core install rather than offered as an extra.

griffe is the Python docstring parser, which is consistent with the tool mechanism being a decorator over a documented signature, and genai-prices suggests a shipped table of model costs.

uvicorn in the core list suggests the package can also run a server, which is not something the README's four usage sections mention.

Prebuilt agents are a pull request, and there are two directories

The prebuilt section describes a collection rather than a catalogue, and the mechanism is a pull request.

Prebuilt autonomous agents are described as ready-to-run agents built by the Upsonic community, each packaging a skill, a system prompt and a first message, so you can go from install to running in seconds. The collection is open to contributions, and the README's phrasing is bring your agent and open a PR.

That triple is the whole format: a skill, a system prompt and a first message. An agent that is meant to be picked up and run immediately is defined by what it knows and what it is told to do first, not by code.

The repository layout is slightly confusing here. There is a prebuilt_autonomous_agents/ directory at the top level, and the contribution link points at src/upsonic/prebuilt. So the collection that ships and the path you contribute to are two different places in the tree, which is worth checking before you work out where your agent belongs.

Other top level entries tell you what else the project does. benchmarks/ for performance work, notebooks/, documents/, examples, tests/ with the docker-compose smoke tests the Makefile expects, a uv.lock and a .python-version for the toolchain, and release-please-config.json with .release-please-manifest.json for automated releases.

Editorial conclusion

Take Upsonic when you want an agent that can act on your machine and you want the blast radius written down as a single workspace directory, or when you want to try an agent with no code beyond a Task string. Leave it if you cannot accept a telemetry SDK in the dependency tree, because sentry-sdk with the opentelemetry extra is a hard requirement rather than an option. Verify three things. Read the install path you will actually use, since the README offers both uv pip install upsonic and the plain pip form, and the manifest pins psutil to an exact version while every other core dependency floats. Check your Python is 3.10 or later and inside the classifier range, which stops at 3.12. And decide on the storage extra before you write code against it, because the backends sit behind separate extras plus one vectordb extra that installs several at once.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Upsonic/Upsonic on GitHub