Aksara

An async PostgreSQL backend framework that generates REST APIs and authorized MCP tools from the same model and policy boundary.

What is Aksara?

Aksara is a Python 3.11+ framework for async PostgreSQL applications. Define an ORM model and a ModelViewSet, then use the same schema and application policy for generated REST routes and MCP tools.

The v0.6 stable contract covers the ORM, migrations, generated REST, authentication and server-owned Principal, permissions and PolicyEngine, tenant isolation, core CLI and Doctor, PostgreSQL background tasks, and MCP Streamable HTTP execution at /mcp/.

Planner behavior, provider-specific quality, process-local investigation sessions, autonomous workflows, memory, and Studio AI internals remain experimental. Aksara is pre-1.0; read the exact stability contract before production adoption.

Why Aksara?

REST callers and AI agents often reach the same data through separate code and security paths. Aksara generates both surfaces from one model/ViewSet definition and rechecks identity, permissions, policy, tenant, and field-write rules when a tool actually runs. The production tenant claim also depends on a restricted PostgreSQL role and forced RLS.

10-Minute Quickstart

Aksara requires PostgreSQL.

python -m venv .venv
source .venv/bin/activate
pip install "aksara-framework==0.6.1"
aksara startproject opsdesk
cd opsdesk
aksara dbsetup

Open app/models.py and define a model:

from aksara import Model, fields


class Incident(Model):
    title = fields.String(max_length=200, ai_description="Short summary")
    resolved = fields.Boolean(
        default=False,
        ai_description="Resolution state",
        ai_agent_writable=False,
    )
    notes = fields.Text(nullable=True, ai_sensitive=True)

    class Meta:
        table_name = "incidents"
        ai_agent_exposed = True

Open app/views.py:

from aksara import ModelViewSet

from .models import Incident


class IncidentViewSet(ModelViewSet):
    model = Incident
    prefix = "/api/incidents"
    ai_exposed = True

Then import IncidentViewSet in app/urls.py, add it to urlpatterns, and run:

aksara makemigrations --app app.models
aksara migrate
aksara doctor launch-check
aksara dev

Open http://127.0.0.1:8000/docs for generated REST OpenAPI. The scaffold keeps MCP, provider-backed AI, and Studio disabled until you configure them.

REST and MCP

The two MCP-related paths have different meanings:

MCP requires trusted server-side authentication that resolves the bearer credential into a Principal; enabling the route does not verify credentials for your application. Follow the complete MCP quickstart for the copy-pasteable model → migration → REST → Principal → official client → persisted invocation path.

Core Features

MCP replay state, approval workflow storage, and audit retention are bounded or application-owned in v0.6. Cross-worker durable operations are planned for v0.7 and are not part of v0.6.1.

Security boundary

Applications verify credentials and resolve a server-owned Principal. Aksara then applies covered permission, object, policy, field, tenant, ORM transaction, and RLS checks to REST and MCP execution. Schemas and hidden UI controls are helpful descriptions; they are not authorization controls.

For production:

aksara doctor security-check
aksara doctor production-check --release

Read the Security Overview and Production Hardening guide. Release gates and security tests provide repository evidence; they are not an external audit or certification.

Configuration

The global aksara.conf.settings object is the runtime source of truth. Use environment variables for deploy-time values and configure(...) for explicit Python overrides. Precedence is explicit configuration, AKSARA_* environment variables, supported aliases such as DATABASE_URL, then defaults.

DATABASE_URL=postgresql://user:password@localhost:5432/opsdesk
AKSARA_DEBUG=true
AKSARA_MCP_ENABLED=false
AKSARA_AI_ENABLED=false
AKSARA_ENABLE_STUDIO=false

An AKSARA = {...} dictionary does not configure the runtime. See the Settings Reference.

Open Studio

Studio is an experimental inspection and AI surface at /studio/ui. It is disabled in new projects. Enabling it requires its secret/authentication and production exposure settings; see the Studio guide.

Use AI

Provider-backed prompt execution is optional and experimental. Configure the current AI Hub path when you need it:

aksara ai-hub configure
aksara ai-hub status
aksara ai-hub doctor

There is no public AgentRuntime or Planner class in v0.6.1. The documented real primitives remain experimental and are described in the AI Mode guide.

Use MCP

Set AKSARA_MCP_ENABLED=true only after adding server-side Principal resolution, then connect an official MCP client to http://127.0.0.1:8000/mcp/. MCP does not require an AI model provider.

Examples

• Basic app
• Blog
• CRM
• Multi-tenant app
• Support Desk production reference

From a source checkout, validate bundled examples with:

aksara examples validate --format json

Documentation

• Installation
• First Project
• MCP Quickstart
• ORM
• API
• Security
• CLI
• Runtime compatibility

Roadmap

v0.6.1 aligns documentation, scaffolding, configuration, package metadata, and installed-wheel validation with the v0.6 product. It does not add the v0.7 durable-operation architecture. See the Roadmap.

Contributing

Read the Contributing Guide and Code of Conduct. Run the relevant tests and strict documentation build before opening a pull request.

License

MIT